randrproto.txt 108 KB
Newer Older
1
	       The X Resize, Rotate and Reflect Extension
Keith Packard's avatar
Keith Packard committed
2
3
			     Version 1.6.0
			       2017-04-01
4

5
6
7
8
9
			      Jim Gettys
			   Jim.Gettys@hp.com
		     Cambridge Research Laboratory
				HP Labs
			Hewlett Packard Company
10

11
			     Keith Packard
Keith Packard's avatar
Keith Packard committed
12
			  keithp@keithp.com
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
13
14
15
16
17

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
18
screen. It is based on the X Resize and Rotate Extension as specified
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
19
20
in the Proceedings of the 2001 Usenix Technical Conference [RANDR].

21
RandR as implemented and integrated into the X server differs in
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
22
23
24
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
25
document and in the implementation has been removed from the
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
26
27
28
protocol described here, as it has been overtaken by events.

These events include:
29
      ► Modern toolkits (in this case, GTK+ 2.x) have progressed to the point
30
	of implementing migration between screens of arbitrary depths
31
      ► The continued advance of Moore's law has made limited amounts of VRAM
32
	less of an issue, reducing the pressure to implement depth switching
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
33
	on laptops or desktop systems
34
      ► The continued decline of legacy toolkits whose design would have
35
	required depth switching to support migration
36
      ► The lack of depth switching implementation experience in the
37
	intervening time, due to events beyond our control
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
38
39
40
41

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

43
44
45
46
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
Keith Packard's avatar
Keith Packard committed
47
protocol. It may be implemented at a later time if resources and
48
interests permit as a revision to the protocol described here, which will
49
remain a stable base for applications. The protocol described here has been
50
51
52
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.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
53

54
55
56
57
58
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,
59
60
61
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
62
may be located anywhere within the screen.
63
64

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

68
To extend RandR for this model, we separate out the output, CRTC and screen
69
70
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
71
72
73
74
75
76
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.
77
78
79

Additional requests and events are provided for this new functionality.

80
81
82
83
84
85
       ┌────────────────────────────────┬──────────┐
    ┏━━━━━━━┳───────────────┐       ╔════════╗ ╔════════╗
    ┃   1   ┃               │       ║   A    ║ ║   B    ║
    ┃   ┏━━━╋━━━━━━━━━━━━━━━┫       ║        ║ ║        ║
    ┣━━━╋━━━┛               ┃       ╚════════╝ ╚════════╝
    │   ┃         2         ┃─────────────────┐
86
    │   ┃                   ┃        ╔═══════════════════╗
87
88
89
    │   ┃                   ┃        ║                   ║
    │   ┗━━━━━━━━━━━━━━━━━━━┫        ║        C          ║
    └───────────────────────┘        ║                   ║
90
91
92
    ┌──────┐  ┏━━━━┓  ╔══════╗       ║                   ║
    │screen│  ┃CRTC┃  ║output║       ╚═══════════════════╝
    └──────┘  ┗━━━━┛  ╚══════╝
93
94

In this picture, the screen is covered (incompletely) by two CRTCs. CRTC1
95
96
97
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
98
99
the screen using a different mode line.

100
101
RandR provides information about each available CRTC and output; the
connection between CRTC and output is under application control, although
102
103
104
105
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.

106
107
108
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
109
capabilities without fundamentally changing the extension again. The
110
111
112
113
114
115
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.
116
117
118
119

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

Keith Packard's avatar
Keith Packard committed
120
121
1.4 Introduction to version 1.4 of the extension

Dave Airlie's avatar
Dave Airlie committed
122
Version 1.4 adds an optional Border property.
Keith Packard's avatar
Keith Packard committed
123

124
125
126
127
128
129
   • 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.

Dave Airlie's avatar
Dave Airlie committed
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
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.

150
151
1.5. Introduction to version 1.5 of the extension

152
153
154
155
156
157
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.

158
159
160
161
162
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.

Giuseppe Bilotta's avatar
Giuseppe Bilotta committed
163
 • Each Monitor is associated with a list of outputs (which may be
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
   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
Giuseppe Bilotta's avatar
Giuseppe Bilotta committed
179
from the logical subsets of the screen that applications should
180
181
182
183
184
185
186
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.

187
188
189
190
191
192
193
194
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.

Keith Packard's avatar
Keith Packard committed
195
196
1.6. Introduction to version 1.6 of the extension

197
Version 1.6 adds resource leasing and non desktop output management.
Keith Packard's avatar
Keith Packard committed
198

199
 • A “Lease” is a collection of crtcs and outputs which are made
Keith Packard's avatar
Keith Packard committed
200
201
202
203
204
   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.

205
206
207
208
209
210
211
212
213
 • 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.

214
1.99 Acknowledgments
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
215

216
217
218
219
220
221
222
223
224
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
225
Matthew Tippett and Kevin Martin for splitting outputs and CRTCs to more
226
fully expose what video hardware can do
227
228
229
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.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
230

231
			      ❧❧❧❧❧❧❧❧❧❧❧
232

Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
233
234
2. Screen change model

235
236
237
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,
Giuseppe Bilotta's avatar
Giuseppe Bilotta committed
238
or, eventually, the hotplug of a display card entirely on buses such as
239
240
241
242
243
244
245
246
247
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).
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
248
249

Interested applications are notified whenever the screen configuration
250
changes, providing the current size of the screen and subpixel order (see
Keith Packard's avatar
Keith Packard committed
251
the Render extension [RENDER]), to enable proper rendering of subpixel
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
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
Keith Packard's avatar
Keith Packard committed
269
screen structure, as they generally use the values in the connections Display
270
271
272
273
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).
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
274

275
			      ❧❧❧❧❧❧❧❧❧❧❧
276

Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
277
278
3. Data Types

279
280
281
282
283
284
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.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
285

286
			      ❧❧❧❧❧❧❧❧❧❧❧
287

Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
288
289
4. Errors

290
291
292
293
294
295
296
297
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.
Dave Airlie's avatar
Dave Airlie committed
298
299
Provider
	A value for a PROVIDER argument does not name a defined PROVIDER.
Keith Packard's avatar
Keith Packard committed
300
301
Lease
	A value for a LEASE argument does not name a defined LEASE
302

303
			      ❧❧❧❧❧❧❧❧❧❧❧
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
304
305
306

5. Protocol Types

307
308
309
310
311
RRCONFIGSTATUS { Success
		 InvalidConfigTime
		 InvalidTime
		 Failed }

312
313
314
	A value of type RRCONFIGSTATUS returned when manipulating the output
	configuration or querying information from the server that has some
	time-dependency.
315

316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
	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
331
	implementer, you find this error code required, please submit the
332
333
334
335
	hardware constraints that exist so that a future version of the
	extension can correctly capture the configuration constraints in
	your system.

336
337
338
339
340
341
ROTATION { Rotate_0
	   Rotate_90
	   Rotate_180
	   Rotate_270
	   Reflect_X
	   Reflect_Y }
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
342

343
344
345
346
	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.

347
RRSELECTMASK { RRScreenChangeNotifyMask
348
	       RRCrtcChangeNotifyMask (New in version 1.2)
349
	       RROutputChangeNotifyMask (New in version 1.2)
350
351
352
353
	       RROutputPropertyNotifyMask (New in version 1.2)
	       RRProviderChangeNotifyMask (New in version 1.4)
	       RRProviderPropertyNotifyMask (New in version 1.4)
	       RRResourceChangeNotifyMask (New in version 1.4) }
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
354

355
356
SIZEID { CARD16 }

357
MODE { XID or None }
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
358

359
CRTC { XID }
360

361
OUTPUT { XID }
362

363
364
CONNECTION { Connected, Disconnected, UnknownConnection }

365
366
367
	This value provides an indication of whether an output is actually
	connected to a monitor or other presentation device.

368

369
370
SCREENSIZE [ widthInPixels, heightInPixels: CARD16
	     widthInMillimeters, heightInMillimeters: CARD16 ]
371

372
373
374
375
376
377
378
379
380
381
382
383
384
385
MODEFLAG { HSyncPositive
	   HSyncNegative
	   VSyncPositive
	   VSyncNegative
	   Interlace
	   DoubleScan
	   CSync
	   CSyncPositive
	   CSyncNegative
	   HSkewPresent
	   BCast
	   PixelMultiplex
	   DoubleClock
	   ClockDivideBy2 }
386

387
MODEINFO [ id: MODE
388
	   name: STRING
389
390
391
392
	   width, height: CARD16
	   dotClock: CARD32
	   hSyncStart, hSyncEnd, hTotal, hSkew: CARD16
	   vSyncStart, vSyncEnd, vTotal: CARD16
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
	   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)
412

413
414
415
416
417
TRANSFORM     [
                        p11, p12, p13:  FIXED
                        p21, p22, p23:  FIXED
                        p31, p32, p33:  FIXED
              ]
418

419
			      ❧❧❧❧❧❧❧❧❧❧❧
420

Dave Airlie's avatar
Dave Airlie committed
421
422
423
424
425
5.5. Protocol Types added in version 1.4 of the extension

PROVIDER { XID }

PROVIDER_CAPS { SourceOutput, SinkOutput, SourceOffload, SinkOffload }
Alan Coopersmith's avatar
Alan Coopersmith committed
426
	Capabilities for this provider:
Dave Airlie's avatar
Dave Airlie committed
427
428
429
430
431
432
433
	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.

			      ❧❧❧❧❧❧❧❧❧❧❧

434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
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 }

			      ❧❧❧❧❧❧❧❧❧❧❧

Keith Packard's avatar
Keith Packard committed
449
450
451
452
453
454
5.7. Protocol Types added in version 1.6 of the extension

LEASE { XID }

			      ❧❧❧❧❧❧❧❧❧❧❧

Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
455
456
457
458
6. Extension Initialization

The name of this extension is "RANDR".

Keith Packard's avatar
Keith Packard committed
459
460
┌───
    RRQueryVersion
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
461
462
	client-major-version:	CARD32
	client-minor-version:	CARD32
Keith Packard's avatar
Keith Packard committed
463

Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
464
465
	major-version:		CARD32
	minor-version:		CARD32
Keith Packard's avatar
Keith Packard committed
466
└───
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
467
468
469

	The client sends the highest supported version to the server
	and the server sends the highest version it supports, but no
470
	higher than the requested version. Major versions changes can
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
471
472
473
474
475
	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.

476
			      ❧❧❧❧❧❧❧❧❧❧❧
477

Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
478
479
7. Extension Requests

Keith Packard's avatar
Keith Packard committed
480
481
┌───
    RRSelectInput
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
482
483
	window: WINDOW
	enable: SETofRRSELECTMASK
Keith Packard's avatar
Keith Packard committed
484
└───
485
	Errors: Window, Value
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
486

487
	If 'enable' is RRScreenChangeNotifyMask, RRScreenChangeNotify events
488
	will be sent when the screen configuration changes, either from
489
490
491
492
	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.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
493

494
	New for version 1.2:
495

496
497
	If 'enable' contains RRCrtcChangeNotifyMask, RRCrtcChangeNotify events
	will be sent when the configuration for a CRTC associated with the
498
499
500
	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
501
502
	the client connected, to avoid race conditions.

503
504
	If 'enable' contains RROutputChangeNotifyMask, RROutputChangeNotify
	events will be sent when the configuration for an output associated with
505
	the screen changes, either through this protocol extension or due to
506
507
508
	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.
509
510
511
512

	If 'enable' contains RROutputPropertyNotifyMask,
	RROutputPropertyNotify events will be sent when properties change on
	this output.
513

514
515
516
517
518
519
520
521
522
523
524
525
526
527
	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.

Keith Packard's avatar
Keith Packard committed
528
529
┌───
    RRSetScreenConfig
530
	window: WINDOW
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
531
532
	timestamp: TIMESTAMP
	config-timestamp: TIMESTAMP
533
	size-id: SIZEID
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
534
535
	rotation: ROTATION
	rate: CARD16
Keith Packard's avatar
Keith Packard committed
536

537
	status: RRCONFIGSTATUS
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
538
539
540
541
	new-timestamp: TIMESTAMP
	config-timestamp: TIMESTAMP
	root: WINDOW
	subpixelOrder: SUBPIXELORDER
Keith Packard's avatar
Keith Packard committed
542
└───
543
	Errors: Value, Match
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
544

545
546
547
	If 'timestamp' is less than the time when the configuration was last
	successfully set, the request is ignored and InvalidTime returned in
	status.
548

549
550
	If 'config-timestamp' is not equal to when the server's screen
	configurations last changed, the request is ignored and
551
	InvalidConfigTime returned in status. This could occur if the
552
553
554
555
556
557
558
559
560
561
562
	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.
563

564
565
	This request sets the screen to the specified size, rate, rotation
	and reflection.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
566

567
568
	When this request succeeds, 'status' contains Success and the
	requested changes to configuration will have been made.
569

570
571
	'new-time-stamp' contains the time at which this request was
	executed.
572

573
574
	'config-timestamp' contains the time when the possible screen
	configurations were last changed.
575

576
	'root' contains the root window for the screen indicated by the
577
	window.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
578

579
580
	'subpixelOrder' contains the resulting subpixel order of the screen
	to allow correct subpixel rendering.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
581

582
583
	Value errors are generated when 'rotation', 'rate' or 'size-id'
	are invalid.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
584

585
586
┌───
    RRGetScreenInfo
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
587
	window: WINDOW
588

Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
589
590
591
592
	rotations: SETofROTATION
	root: WINDOW
	timestamp: TIMESTAMP
	config-timestamp: TIMESTAMP
593
	size-id: SIZEID
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
594
595
596
597
	rotation: ROTATION
	rate: CARD16
	sizes: LISTofSCREENSIZE
	refresh: LISTofREFRESH
598
└───
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
599

600
	Errors: Window
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
601

602
603
	RRGetScreenInfo returns information about the current and available
	configurations for the screen associated with 'window'.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
604

605
606
	'rotations' contains the set of rotations and reflections supported
	by the screen.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
607

608
	'root' is the root window of the screen.
609

610
	'config-timestamp' indicates when the screen configuration
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
611
612
613
	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
614
615
	in the face of race conditions.

616
	'timestamp' indicates when the configuration was last set.
617

618
	'size-id' indicates which size is active.
619

620
	'rate' is the current refresh rate. This is zero when the refresh
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
621
622
	rate is unknown or on devices for which refresh is not relevant.

623
	'sizes' is the list of possible frame buffer sizes (at the normal
Giuseppe Bilotta's avatar
Giuseppe Bilotta committed
624
	orientation). Each size indicates both the linear physical size of
625
	the screen and the pixel size.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
626

627
	'refresh' is the list of refresh rates for each size. Each element
Keith Packard's avatar
Keith Packard committed
628
	of 'sizes' has a corresponding element in 'refresh'. An empty list
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
629
630
631
632
633
	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
634
	list.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
635

636
7.1. Extension Requests added in version 1.2 of the extension
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
637

638
As introduced above, version 1.2 of the extension splits the screen size
639
640
from the crtc and output configuration, permitting the subset of the screen
presented by multiple outputs to be configured. As a separate notion, the
641
size of the screen itself may be arbitrarily configured within a defined
642
643
644
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.
645

646
647
┌───
    RRGetScreenSizeRange
648
	window: WINDOW
649

650
651
	CARD16	minWidth, minHeight
	CARD16	maxWidth, maxHeight
652
└───
653
	Errors: Window
654
655
656
657

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

658
659
┌───
    RRSetScreenSize
660
	window: WINDOW
661
662
	width: CARD16
	height: CARD16
663
664
	width-in-millimeters: CARD32
	height-in-millimeters: CARD32
665
└───
666
	Errors: Window, Match, Value
667
668
669
670
671
672

	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.

673
674
675
676
677
	'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.

678
679
680
681
682
	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).
Matthias Hopf's avatar
Matthias Hopf committed
683

684
685
┌───
    RRGetScreenResources
686
	window: WINDOW
687

688
689
	timestamp: TIMESTAMP
	config-timestamp: TIMESTAMP
690
691
692
693
	crtcs: LISTofCRTC
	outputs: LISTofOUTPUT
	modes: LISTofMODEINFO
└───
694
695
	Errors: Window

696
697
	RRGetScreenResources returns the list of outputs and crtcs connected
	to the screen associated with 'window'.
698
699

	'timestamp' indicates when the configuration was last set.
700

701
702
703
704
705
706
	'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.

707
	'crtcs' contains the list of CRTCs associated with the screen.
708

709
	'outputs' contains the list of outputs associated with the screen.
710

711
	'modes' contains the list of modes associated with the screen
712

713
714
	This request explicitly asks the server to ensure that the
	configuration data is up-to-date wrt the hardware. If that requires
Adam Jackson's avatar
Adam Jackson committed
715
716
717
718
	polling, this is when such polling would take place.  If the
	current configuration is all that's required, use
	RRGetScreenResourcesCurrent instead.

719
720
┌───
    RRGetOutputInfo
721
	output: OUTPUT
722
723
724
	config-timestamp: TIMESTAMP

	status: RRCONFIGSTATUS
725
	timestamp: TIMESTAMP
726
	crtc: CRTC
727

728
	name: STRING
729
	connection: CONNECTION
730
	subpixel-order: SUBPIXELORDER
731
	widthInMillimeters, heightInMillimeters: CARD32
732
733
	crtcs: LISTofCRTC
	clones: LISTofOUTPUT
734
	modes: LISTofMODE
735
	num-preferred: CARD16
736
└───
Keith Packard's avatar
Keith Packard committed
737
	Errors: Output
738
739

	RRGetOutputInfo returns information about the current and available
740
741
	configurations 'output'.

742
743
744
745
	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.
746
747

	'timestamp' indicates when the configuration was last set.
748

749
750
751
752
753
754
755
756
757
758
	'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.
759

760
761
762
	'subpixel-order' contains the resulting subpixel order of the
	connected device to allow correct subpixel rendering.

763
764
765
766
	'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.

767
768
769
770
771
772
773
774
775
776
777
778
779
	'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.

780
781
782
783
	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.

784
785
786
787
788
789
	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.

790
791
┌───
    RRListOutputProperties
792
	output:OUTPUT
793

794
	atoms: LISTofATOM
795
796
797
798
799
800
└───
	Errors: Output

	This request returns the atoms of properties currently defined on
	the output.

801
802
803
804
805
806
	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.

807
808
809
810
811
┌───
    RRQueryOutputProperty
	output: OUTPUT
	property: ATOM

812
	pending: BOOL
813
814
815
816
817
818
819
820
821
822
823
824
825
826
	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.
827

828
829
830
831
832
833
834
835
836
	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.
837

838
839
840
841
842
843
	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.

844
845
846
847
┌───
    RRConfigureOutputProperty
	output: OUTPUT
	property: ATOM
848
	pending: BOOL
849
850
851
852
853
854
855
856
857
858
859
	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.

860
861
862
	If the specified property does not exist for the specified output,
	it is created with an empty value and None type.

863
864
┌───
    RRChangeOutputProperty
865
	output: OUTPUT
866
867
868
869
870
871
	property, type: ATOM
	format: {8, 16, 32}
	mode: { Replace, Prepend, Append }
	data: LISTofINT8 or LISTofINT16 or LISTofINT32
└───
	Errors: Alloc, Atom, Match, Value, Output
872

873
874
875
876
877
878
879
880
	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.
881
882
883
884
885
886

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

888
889
890
891
892
893
894
895
896
897
	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
898
	dynamically.
899
900
901

┌───
    RRDeleteOutputProperty
902
	output: OUTPUT
903
904
905
	property: ATOM
└───
	Errors: Atom, Output
906

907
908
909
910
911
912
	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
913
	output: OUTPUT
914
915
916
917
	property: ATOM
	type: ATOM or AnyPropertyType
	long-offset, long-length: CARD32
	delete: BOOL
918
	pending: BOOL
919
920
921
922
923
924
925
926
927
928
929

	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
930
931
	case.

932
933
934
935
936
	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
937
938
	argument is ignored in this case.

939
940
941
942
943
944
	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:

945
		N = actual length of the stored property in bytes
946
947
948
949
950
				  (even if the format is 16 or 32)
		I = 4 × offset
		T = N - I
		L = MINIMUM(T, 4 × long-length)
		A = N - (I + L)
951

952
953
954
955
956
957
958
959
960
	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.
961

962
963
964
965
966
967
	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.

968
969
┌───
    RRCreateMode
970
	window: WINDOW
971
972
	modeinfo: MODEINFO

973
	mode: MODE
974
975
└───
	Errors: Window, Name, Value
976

977
978
979
980
	'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.
981

982
	The returned 'mode' provides the id for the mode.
983

984
985
┌───
    RRDestroyMode
986
	mode: MODE
987
988
989
990
991
992
993
└───
	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.
994

995
996
997
998
999
1000
1001
1002
┌───
    RRAddOutputMode
	output: OUTPUT
	mode: MODE
└───
	Errors: Output, Mode, Match

	'output' indicates which output is to be configured.
1003

1004
	'mode' specifies which mode to add. If 'mode' is not valid for
1005
	'output', then a Match error is generated.
1006
1007

	This request generates OutputChangeNotify events.
1008

1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
┌───
    RRDeleteOutputMode
	output: OUTPUT
	mode: MODE
└───
	Errors: Output, Mode

	'output' indicates which output is to be configured.

	'mode' specifies which mode to delete. 'mode' must have been added
	with RRAddOutputMode, else an Access error is returned. 'mode' must
	not be active, else a Match error is returned.

	This request generates OutputChangeNotify events.

┌───
    RRGetCrtcInfo
	crtc: CRTC
	config-timestamp: TIMESTAMP

	status: RRCONFIGSTATUS
1030
	timestamp: TIMESTAMP
1031
	x, y: INT16
1032
	width, height: CARD16
1033
	mode: MODE
1034
	rotation: ROTATION
1035
	outputs: LISTofOUTPUT
1036

1037
	rotations: SETofROTATION
1038
1039
	possible-outputs: LISTofOUTPUT
└───
1040

1041
	Errors: Window
1042

1043
	RRGetCrtcInfo returns information about the current and available
1044
1045
	configurations for the specified crtc connected to the screen
	associated with 'window'.
1046

1047
1048
1049
1050
	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.
1051

1052
	'timestamp' indicates when the configuration was last set.
1053

1054
1055
	'x' and 'y' indicate the position of this CRTC within the screen
	region. They will be set to 0 when the CRTC is disabled.
1056

1057
1058
	'width' and 'height' indicate the size of the area within the screen
	presented by this CRTC. This may be different than the size of the
1059
1060
	mode due to rotation, the projective transform, and the Border property
	described below.  They will be set to 0 when the CRTC is disabled.
1061

1062
1063
	'mode' indicates which mode is active, or None indicating that the
	CRTC has been disabled and is not displaying the screen contents.
1064
1065

	'rotation' indicates the active rotation. It is set to Rotate_0
1066
	when the CRTC is disabled.
1067

1068
1069
1070
	'outputs' is the list of outputs currently connected to this CRTC
	and is empty when the CRTC is disabled.

1071
	'rotations' contains the set of rotations and reflections supported
1072
	by the CRTC.
1073

1074
1075
	'possible-outputs' lists all of the outputs which may be connected
	to this CRTC.
1076

1077
1078
┌───
    RRSetCrtcConfig
1079
	crtc: CRTC
1080
1081
	timestamp: TIMESTAMP
	config-timestamp: TIMESTAMP
1082
	x, y: INT16
1083
	mode: MODE
1084
	rotation: ROTATION
1085
	outputs: LISTofOUTPUT
1086

1087
	status: RRCONFIGSTATUS
1088
	new-timestamp: TIMESTAMP
1089
└───
1090
1091
1092
1093
1094
	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.
1095

1096
1097
	If 'config-timestamp' is not equal to when the monitor's
	configuration last changed, the request is ignored and
1098
	InvalidConfigTime returned in status. This could occur if the
1099
1100
1101
1102
1103
1104
1105
1106
1107
	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.

1108
1109
1110
1111
	'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.
1112
1113
1114
1115
1116
1117

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

1118
1119
	'outputs' contains the set of outputs that this CRTC should be
	connected to. The set must be among the list of acceptable output
1120
1121
	sets for this CRTC or a Match error results.

1122
	If 'mode' is None, then 'outputs' must be empty, else a Match error
Keith Packard's avatar
Keith Packard committed
1123
	results. Conversely, if 'mode' is not None, then 'outputs' must not be
1124
	empty, else a Match error results.
1125

1126
1127
1128
	This request may fail for other indeterminate reasons, in which case
	'status' will be set to Failed and no configuration change will be
	made.
1129

1130
1131
1132
1133
1134
1135
1136
	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.
1137

1138
1139
1140
1141
1142
	If panning is enabled, the width and height of the panning and the
	tracking areas are clamped to the new mode size.
	Disabled panning axes remain disabled.
	Panning borders are disabled if their requirements are no longer met
	(see RRSetPanning).
Matthias Hopf's avatar
Matthias Hopf committed
1143

1144
1145
	When this request succeeds, 'status' contains Success and the
	requested changes to configuration will have been made.
1146

1147
1148
	'new-time-stamp' contains the time at which this request was
	executed.
1149

1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
┌───
    RRGetCrtcGammaSize
	crtc: CRTC

	size: CARD16
└───
	Errors: Crtc

	This request returns the size of the gamma ramps used by 'crtc'.

┌───
    RRGetCrtcGamma
	crtc: CRTC

1164
	red: LISTofCARD16
1165
1166
	green: LISTofCARD16
	blue: LISTofCARD16
1167
└───
1168
	Errors: Crtc
1169

1170
1171
1172
	This request returns the currently set gamma ramps for 'crtc'.  All
	three lists will be the size returned by the RRGetCrtcGammaSize
	request.
1173

1174
1175
1176
1177
1178
1179
1180
1181
┌───
    RRSetCrtcGamma
	crtc: CRTC
	red: LISTofCARD16
	green: LISTofCARD16
	blue: LISTofCARD16
└───
	Errors: Crtc, Match
1182

1183
1184
1185
	This request sets the gamma ramps for 'crtc'. All three lists
	must be the size returned by RRGetCrtcGammaSize else a Value error
	results.
Kaleb Keithley Keithley's avatar
Kaleb Keithley Keithley committed
1186

Adam Jackson's avatar
Adam Jackson committed
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196