-
Notifications
You must be signed in to change notification settings - Fork 0
/
randrproto.txt
3430 lines (2912 loc) · 108 KB
/
randrproto.txt
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
The X Resize, Rotate and Reflect Extension
Version 1.6.0
2017-04-01
Jim Gettys
Cambridge Research Laboratory
HP Labs
Hewlett Packard Company
Keith Packard
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 switching 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 implemented 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.
1.3 Introduction to version 1.3 of the extension
Version 1.3 builds on the changes made with version 1.2 and adds some new
capabilities without fundamentally changing the extension again. The
following features are added in this version:
• Projective Transforms. The implementation work for general rotation
support made it trivial to add full projective transformations. These
can be used to scale the screen up/down as well as perform projector
keystone correct or other effects.
• Panning. It was removed with RandR 1.2 because the old semantics didn't
fit any longer. With RandR 1.3 panning can be specified per crtc.
1.4 Introduction to version 1.4 of the extension
Version 1.4 adds an optional Border property.
• An optional Border property. This property allows a client to
specify that the viewport of the CRTC is smaller than the active
display region described its mode. This is useful, for example,
for compensating for the overscan behavior of certain
televisions.
Version 1.4 adds a new object called a provider object. A provider object
represents a GPU or virtual device providing services to the X server.
Providers have a set of abilities and a set of possible roles.
Provider objects are used to control multi-GPU systems. Provider roles can
be dynamically configured to provide support for:
1) Output slaving: plug in a USB device, but have its output rendered
using the main GPU. On some dual-GPU laptops, the second GPU isn't
connected to the LVDS panel, so we need to use the first GPU as an output
slave for the second GPU.
2) offload - For dual-GPU laptops, allow direct rendered applications to be run
on the second GPU and display on the first GPU.
3) GPU switching - Allow switching between two GPUs as the main screen
renderer.
4) multiple GPU rendering - This replaces Xinerama.
1.5. Introduction to version 1.5 of the extension
Version 1.5 adds an optional TILE property to outputs.
• An optional TILE property.
This property is used to denote individual tiles in a tiled monitor
configuration, as exposed via DisplayID v1.3.
Version 1.5 adds monitors
• A 'Monitor' is a rectangular subset of the screen which represents
a coherent collection of pixels presented to the user.
• Each Monitor is associated with a list of outputs (which may be
empty).
• When clients define monitors, the associated outputs are removed from
existing Monitors. If removing the output causes the list for that
monitor to become empty, that monitor will be deleted.
• For active CRTCs that have no output associated with any
client-defined Monitor, one server-defined monitor will
automatically be defined of the first Output associated with them.
• When defining a monitor, setting the geometry to all zeros will
cause that monitor to dynamically track the bounding box of the
active outputs associated with them
This new object separates the physical configuration of the hardware
from the logical subsets of the screen that applications should
consider as single viewable areas.
1.5.1. Relationship between Monitors and Xinerama
Xinerama's information now comes from the Monitors instead of directly
from the CRTCs. The Monitor marked as Primary will be listed first.
1.5.2. Clarification of Output lifetimes
With dynamic connectors being a possibility with the introduction of
DisplayPort multistream (MST), a lot of RandR clients can't handle the
XID BadMatch when a RandR output disappears. This is to clarify that
going forward the X server will not remove outputs dynamically,
just mark them as disconnected.
1.6. Introduction to version 1.6 of the extension
Version 1.6 adds resource leasing and non desktop output management.
• A “Lease” is a collection of crtcs and outputs which are made
available to a client for direct access via kernel KMS and DRM
APIs. This is done by passing a suitable file descriptor back to
the client which has access to those resources. While leased, those
resources aren't used by the X server.
• A “non-desktop” output is a device which should not normally be
considered as part of the desktop environment. Head-mounted
displays and the Apple "Touch Bar" are examples of such
devices. A desktop environment should be able to discover which
outputs are connected to such devices and, by default, not present
normal desktop applications on them. This is done by having
RRGetOutputInfo report such devices as Disconnected while reporting
all other information about the device correctly.
1.99 Acknowledgments
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 Tippett and Kevin Martin for splitting outputs and CRTCs to more
fully expose what video hardware can do
Dave Airlie for the 1.4.0 protocol changes and for working through the
implications of MST monitors and encouraging the introduction of the
'Monitor' concept.
❧❧❧❧❧❧❧❧❧❧❧
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 buses 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 enable 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 structure, 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 and transform data types are shared with the Render
extension, and are documented there.
The only datatype defined in the original extension is the screen size,
defined in the normal (0 degree) orientation. Several more are added
in later revisions.
❧❧❧❧❧❧❧❧❧❧❧
4. Errors
Errors are sent using core X error reports.
Output
A value for an OUTPUT argument does not name a defined OUTPUT.
CRTC
A value for a CRTC argument does not name a defined CRTC.
Mode
A value for a MODE argument does not name a defined MODE.
Provider
A value for a PROVIDER argument does not name a defined PROVIDER.
Lease
A value for a LEASE argument does not name a defined LEASE
❧❧❧❧❧❧❧❧❧❧❧
5. Protocol Types
RRCONFIGSTATUS { Success
InvalidConfigTime
InvalidTime
Failed }
A value of type RRCONFIGSTATUS returned when manipulating the output
configuration or querying information from the server that has some
time-dependency.
InvalidConfigTime indicates that the supplied configuration
timestamp does not match the current X server configuration
timestamp. Usually this means that the output configuration has
changed since the timestamp was received by the application.
InvalidTime indicates that the supplied output reconfiguration time
is earlier than the most recent output reconfiguration request.
Generally this indicates that another application has reconfigured
the output using a later timestamp.
Failed is returned whenever the operation is unsuccessful for some
other reason. This generally indicates that the requested output
configuration is unsupported by the hardware. The goal is to make
these limitations expressed by the protocol, but when that isn't
possible it is correct to return this error value. If, as a
implementer, you find this error code required, please submit the
hardware constraints that exist so that a future version of the
extension can correctly capture the configuration constraints in
your system.
ROTATION { Rotate_0
Rotate_90
Rotate_180
Rotate_270
Reflect_X
Reflect_Y }
These values are used both to indicate a set of allowed rotations
and reflections as well as to indicate a specific rotation and
reflection combination.
RRSELECTMASK { RRScreenChangeNotifyMask
RRCrtcChangeNotifyMask (New in version 1.2)
RROutputChangeNotifyMask (New in version 1.2)
RROutputPropertyNotifyMask (New in version 1.2)
RRProviderChangeNotifyMask (New in version 1.4)
RRProviderPropertyNotifyMask (New in version 1.4)
RRResourceChangeNotifyMask (New in version 1.4) }
SIZEID { CARD16 }
MODE { XID or None }
CRTC { XID }
OUTPUT { XID }
CONNECTION { Connected, Disconnected, UnknownConnection }
This value provides an indication of whether an output is actually
connected to a monitor or other presentation device.
SCREENSIZE [ widthInPixels, heightInPixels: CARD16
widthInMillimeters, heightInMillimeters: CARD16 ]
MODEFLAG { HSyncPositive
HSyncNegative
VSyncPositive
VSyncNegative
Interlace
DoubleScan
CSync
CSyncPositive
CSyncNegative
HSkewPresent
BCast
PixelMultiplex
DoubleClock
ClockDivideBy2 }
MODEINFO [ id: MODE
name: STRING
width, height: CARD16
dotClock: CARD32
hSyncStart, hSyncEnd, hTotal, hSkew: CARD16
vSyncStart, vSyncEnd, vTotal: CARD16
modeFlags: SETofMODEFLAG ]
REFRESH [ rates: LISTofCARD16 ]
❧❧❧❧❧❧❧❧❧❧❧
5.1 Data Types defined by the Render extension
These data types use the Render extension definitions; they are shown here
only for convenience:
SUBPIXELORDER { SubPixelUnknown
SubPixelHorizontalRGB
SubPixelHorizontalBGR
SubPixelVerticalRGB
SubPixelVerticalBGR
SubPixelNone }
FIXED 32-bit value (top 16 are integer portion, bottom 16 are fraction)
TRANSFORM [
p11, p12, p13: FIXED
p21, p22, p23: FIXED
p31, p32, p33: FIXED
]
❧❧❧❧❧❧❧❧❧❧❧
5.5. Protocol Types added in version 1.4 of the extension
PROVIDER { XID }
PROVIDER_CAPS { SourceOutput, SinkOutput, SourceOffload, SinkOffload }
Capabilities for this provider:
SourceOutput: This device can source output buffers.
SinkOutput: This device can sink output buffers.
SourceOffload: This device can source offload buffers.
SinkOffload: This device can sink offload buffers.
❧❧❧❧❧❧❧❧❧❧❧
5.6. Protocol Types added in version 1.5 of the extension
MONITORINFO { name: ATOM
primary: BOOL
automatic: BOOL
x: INT16
y: INT16
width: CARD16
height: CARD16
width-in-millimeters: CARD32
height-in-millimeters: CARD32
outputs: LISTofOUTPUT }
❧❧❧❧❧❧❧❧❧❧❧
5.7. Protocol Types added in version 1.6 of the extension
LEASE { XID }
❧❧❧❧❧❧❧❧❧❧❧
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 RRCrtcChangeNotifyMask, RRCrtcChangeNotify events
will be sent when 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 RROutputChangeNotifyMask, RROutputChangeNotify
events will be sent when 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.
If 'enable' contains RROutputPropertyNotifyMask,
RROutputPropertyNotify events will be sent when properties change on
this output.
New for version 1.4:
If 'enable' contains RRProviderChangeNotifyMask,
RRProviderChangeNotify events will be sent whenever the role for a
provider object has changed.
If 'enable' contains RRProviderPropertyNotifyMask,
RRProviderPropertyNotify events will be sent when properties change
on a provider object.
If 'enable' contains RRResourceChangeNotifyMask,
RRResourceChangeNotify events will be sent whenever the set of
available RandR resources associated with the screen has changed.
┌───
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
└───
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 corresponding 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.
If panning is enabled, the width and height of the panning and the
tracking areas are adapted to the new size and clamped afterwards.
Disabled panning axes remain disabled.
Panning borders are disabled if their requirements are no longer met
(see RRSetPanning).
┌───
RRGetScreenResources
window: WINDOW
▶
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
crtcs: LISTofCRTC
outputs: LISTofOUTPUT
modes: LISTofMODEINFO
└───
Errors: Window
RRGetScreenResources returns the list of outputs and crtcs connected
to the screen associated with 'window'.
'timestamp' indicates when the configuration was last set.
'config-timestamp' indicates when the configuration information last
changed. Requests to configure the output 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.
'crtcs' contains the list of CRTCs associated with the screen.
'outputs' contains the list of outputs associated with the screen.
'modes' contains the list of modes associated with the screen
This request explicitly asks the server to ensure that the
configuration data is up-to-date wrt the hardware. If that requires
polling, this is when such polling would take place. If the
current configuration is all that's required, use
RRGetScreenResourcesCurrent instead.
┌───
RRGetOutputInfo
output: OUTPUT
config-timestamp: TIMESTAMP
▶
status: RRCONFIGSTATUS
timestamp: TIMESTAMP
crtc: CRTC
name: STRING
connection: CONNECTION
subpixel-order: SUBPIXELORDER
widthInMillimeters, heightInMillimeters: CARD32
crtcs: LISTofCRTC
clones: LISTofOUTPUT
modes: LISTofMODE
num-preferred: CARD16
└───
Errors: Output
RRGetOutputInfo returns information about the current and available
configurations 'output'.
If 'config-timestamp' does not match the current configuration
timestamp (as returned by RRGetScreenResources), 'status' is set to
InvalidConfigTime and the remaining reply data is empty. Otherwise,
'status' is set to Success.
'timestamp' indicates when the configuration was last set.
'crtc' is the current source CRTC for video data, or Disabled if the
output is not connected to any CRTC.
'name' is a UTF-8 encoded string designed to be presented to the
user to indicate which output this is. E.g. "S-Video" or "DVI".
'connection' indicates whether the hardware was able to detect a
device connected to this output. If the hardware cannot determine
whether something is connected, it will set this to
UnknownConnection.
'subpixel-order' contains the resulting subpixel order of the
connected device to allow correct subpixel rendering.
'widthInMillimeters' and 'heightInMillimeters' report the physical
size of the displayed area. If unknown, or not really fixed (e.g.,
for a projector), these values are both zero.
'crtcs' is the list of CRTCs that this output may be connected to.
Attempting to connect this output to a different CRTC results in a
Match error.
'clones' is the list of outputs which may be simultaneously
connected to the same CRTC along with this output. Attempting to
connect this output with an output not in the 'clones' list
results in a Match error.
'modes' is the list of modes supported by this output. Attempting to
connect this output to a CRTC not using one of these modes results
in a Match error.
The first 'num-preferred' modes in 'modes' are preferred by the
monitor in some way; for fixed-pixel devices, this would generally
indicate which modes match the resolution of the output device.
Changes in version 1.6 of the protocol:
When a “non-desktop” device is connected, the 'connection'
field will report Disconnected but the remaining fields will
report information about the connected device.
┌───
RRListOutputProperties
output:OUTPUT
▶
atoms: LISTofATOM
└───
Errors: Output
This request returns the atoms of properties currently defined on
the output.
Changes in version 1.6 of the protocol:
When a “non-desktop” device is connected, the property list
will be correct for the device, even though RRGetOutputInfo
reports the device as disconnected.
┌───
RRQueryOutputProperty
output: OUTPUT
property: ATOM
▶
pending: BOOL
range: BOOL
immutable: BOOL
valid-values: LISTofINT32
└───
Errors: Name, Atom, Output
If the specified property does not exist for the specified output,
then a Name error is returned.
If 'pending' is TRUE, changes made to property values with
RRChangeOutputProperty will be saved in the pending property value
and be automatically copied to the current value on the next
RRSetCrtcConfig request involving the named output. If 'pending' is
FALSE, changes are copied immediately.
If 'range' is TRUE, then the valid-values list will contain
precisely two values indicating the minimum and maximum allowed
values. If 'range' is FALSE, then the valid-values list will contain
the list of possible values; attempts to set other values will
result in a Value error.
If 'immutable' is TRUE, then the property configuration cannot be
changed by clients. Immutable properties are interpreted by the X
server.
Changes in version 1.6 of the protocol:
When a “non-desktop” device is connected, the property information
will be correct for the device, even though RRGetOutputInfo
reports the device as disconnected.
┌───
RRConfigureOutputProperty
output: OUTPUT
property: ATOM
pending: BOOL
range: BOOL
valid-values: LISTofINT32
└───
Errors: Access, Name, Atom, Output
If the specified property is 'immutable', an Access error is
returned.
Otherwise, the configuration of the specified property is changed to
the values provided in this request.
If the specified property does not exist for the specified output,
it is created with an empty value and None type.
┌───
RRChangeOutputProperty
output: OUTPUT
property, type: ATOM
format: {8, 16, 32}
mode: { Replace, Prepend, Append }
data: LISTofINT8 or LISTofINT16 or LISTofINT32
└───
Errors: Alloc, Atom, Match, Value, Output
This request alters the value of the property for the specified
output. If the property is marked as a 'pending' property, only the
pending value of the property is changed. Otherwise, changes are
reflected in both the pending and current values of the property.
The type is uninterpreted by the server. The format specifies
whether the data should be viewed as a list of 8-bit, 16-bit, or
32-bit quantities so that the server can correctly byte-swap as
necessary.
If the mode is Replace, the previous property value is discarded.
If the mode is Prepend or Append, then the type and format must
match the existing property value (or a Match error results). If
the property is undefined, it is treated as defined with the correct
type and format with zero-length data.
For Prepend, the data is tacked on to the beginning of the existing
data, and for Append, it is tacked on to the end of the existing data.
This request generates a OutputPropertyNotify
The lifetime of a property is not tied to the storing client.
Properties remain until explicitly deleted, until the output is
destroyed, or until server reset (see section 10).
The maximum size of a property is server-dependent and may vary
dynamically.
┌───
RRDeleteOutputProperty
output: OUTPUT
property: ATOM
└───
Errors: Atom, Output
This request deletes the property from the specified window if the
property exists and generates a OutputPropertyNotify event unless
the property does not exist.
┌───
RRGetOutputProperty
output: OUTPUT
property: ATOM
type: ATOM or AnyPropertyType
long-offset, long-length: CARD32
delete: BOOL
pending: BOOL
▶
type: ATOM or None
format: {0, 8, 16, 32}
bytes-after: CARD32
value: LISTofINT8 or LISTofINT16 or LISTofINT32
└───
Errors: Atom, Value, Output
If the specified property does not exist for the specified output,
then the return type is None, the format and bytes-after are zero,
and the value is empty. The delete argument is ignored in this
case.
If the specified property exists but its type does not match the
specified type, then the return type is the actual type of the
property, the format is the actual format of the property (never
zero), the bytes-after is the length of the property in bytes (even
if the format is 16 or 32), and the value is empty. The delete
argument is ignored in this case.
If the specified property exists and either AnyPropertyType is
specified or the specified type matches the actual type of the
property, then the return type is the actual type of the property,
the format is the actual format of the property (never zero), and
the bytes-after and value are as follows, given:
N = actual length of the stored property in bytes
(even if the format is 16 or 32)
I = 4 × offset
T = N - I
L = MINIMUM(T, 4 × long-length)
A = N - (I + L)
If 'pending' is true, and if the property holds a pending value,
then the value returned will be the pending value of the property
rather than the current value. The returned value starts at byte
index I in the property (indexing from 0), and its length in bytes
is L. However, it is a Value error if long-offset is given such
that L is negative. The value of bytes-after is A, giving the
number of trailing unread bytes in the stored property. If delete
is True and the bytes-after is zero, the property is also deleted
from the output, and a RROutputPropertyNotify event is generated.
Changes in version 1.6 of the protocol:
When a “non-desktop” device is connected, the property value
will be correct for the device, even though RRGetOutputInfo
reports the device as disconnected.
┌───
RRCreateMode
window: WINDOW
modeinfo: MODEINFO
▶
mode: MODE
└───
Errors: Window, Name, Value
'modeinfo' provides a new mode for outputs on the screen
associated with 'window'. If the name of 'modeinfo' names an
existing mode, a Name error is returned. If some parameter of the
mode is not valid in some other way, a Value error is returned.
The returned 'mode' provides the id for the mode.
┌───
RRDestroyMode
mode: MODE
└───
Errors: Mode, Access
The user-defined 'mode' is destroyed. 'mode' must name a mode
defined with RRCreateMode, else an Match error is returned. If
'mode' is in use by some CRTC or Output, then an Access error is
returned.
┌───
RRAddOutputMode
output: OUTPUT
mode: MODE
└───
Errors: Output, Mode, Match