randrproto.txt revision 68872e7f
1 The X Resize, Rotate and Reflect Extension 2 Version 1.6.0 3 2017-04-01 4 5 Jim Gettys 6 Jim.Gettys@hp.com 7 Cambridge Research Laboratory 8 HP Labs 9 Hewlett Packard Company 10 11 Keith Packard 12 keithp@keithp.com 13 141. Introduction 15 16The X Resize, Rotate and Reflect Extension, called RandR for short, 17brings the ability to resize, rotate and reflect the root window of a 18screen. It is based on the X Resize and Rotate Extension as specified 19in the Proceedings of the 2001 Usenix Technical Conference [RANDR]. 20 21RandR as implemented and integrated into the X server differs in 22one substantial fashion from the design discussed in that paper: that 23is, RandR 1.0 does not implement the depth switching described in that 24document, and the support described for that in the protocol in that 25document and in the implementation has been removed from the 26protocol described here, as it has been overtaken by events. 27 28These 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 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 38 39Additionally, the requirement to support depth switching might 40complicate other re-engineering of the device independent part of the 41X server that is currently being contemplated. 42 43Rather than further delaying RandR's widespread deployment for a feature 44long wanted by the community (resizing of screens, particularly on laptops), 45or the deployment of a protocol design that might be flawed due to lack of 46implementation experience, we decided to remove depth switching from the 47protocol. It may be implemented at a later time if resources and 48interests permit as a revision to the protocol described here, which will 49remain a stable base for applications. The protocol described here has been 50implemented in the main X.org server, and more fully in the hw/kdrive 51implementation in the distribution, which fully implements resizing, 52rotation and reflection. 53 541.2 Introduction to version 1.2 of the extension 55 56One of the significant limitations found in version 1.1 of the RandR 57protocol was the inability to deal with the Xinerama model where multiple 58monitors display portions of a common underlying screen. In this environment, 59zero or more video outputs are associated with each CRT controller which 60defines both a set of video timings and a 'viewport' within the larger 61screen. This viewport is independent of the overall size of the screen, and 62may be located anywhere within the screen. 63 64The effect is to decouple the reported size of the screen from the size 65presented by each video output, and to permit multiple outputs to present 66information for a single screen. 67 68To extend RandR for this model, we separate out the output, CRTC and screen 69configuration information and permit them to be configured separately. For 70compatibility with the 1.1 version of the protocol, we make the 1.1 requests 71simultaneously affect both the screen and the (presumably sole) CRTC and 72output. The set of available outputs are presented with UTF-8 encoded names 73and may be connected to CRTCs as permitted by the underlying hardware. CRTC 74configuration is now done with full mode information instead of just size 75and refresh rate, and these modes have names. These names also use UTF-8 76encoding. New modes may also be added by the user. 77 78Additional requests and events are provided for this new functionality. 79 80 ┌────────────────────────────────┬──────────┐ 81 ┏━━━━━━━┳───────────────┐ ╔════════╗ ╔════════╗ 82 ┃ 1 ┃ │ ║ A ║ ║ B ║ 83 ┃ ┏━━━╋━━━━━━━━━━━━━━━┫ ║ ║ ║ ║ 84 ┣━━━╋━━━┛ ┃ ╚════════╝ ╚════════╝ 85 │ ┃ 2 ┃─────────────────┐ 86 │ ┃ ┃ ╔═══════════════════╗ 87 │ ┃ ┃ ║ ║ 88 │ ┗━━━━━━━━━━━━━━━━━━━┫ ║ C ║ 89 └───────────────────────┘ ║ ║ 90 ┌──────┐ ┏━━━━┓ ╔══════╗ ║ ║ 91 │screen│ ┃CRTC┃ ║output║ ╚═══════════════════╝ 92 └──────┘ ┗━━━━┛ ╚══════╝ 93 94In this picture, the screen is covered (incompletely) by two CRTCs. CRTC1 95is connected to two outputs, A and B. CRTC2 is connected to output C. 96Outputs A and B will present exactly the same region of the screen using 97the same mode line. Output C will present a different (larger) region of 98the screen using a different mode line. 99 100RandR provides information about each available CRTC and output; the 101connection between CRTC and output is under application control, although 102the hardware will probably impose restrictions on the possible 103configurations. The protocol doesn't try to describe these restrictions, 104instead it provides a mechanism to find out what combinations are supported. 105 1061.3 Introduction to version 1.3 of the extension 107 108Version 1.3 builds on the changes made with version 1.2 and adds some new 109capabilities without fundamentally changing the extension again. The 110following features are added in this version: 111 112 • Projective Transforms. The implementation work for general rotation 113 support made it trivial to add full projective transformations. These 114 can be used to scale the screen up/down as well as perform projector 115 keystone correct or other effects. 116 117 • Panning. It was removed with RandR 1.2 because the old semantics didn't 118 fit any longer. With RandR 1.3 panning can be specified per crtc. 119 1201.4 Introduction to version 1.4 of the extension 121 122Version 1.4 adds an optional Border property. 123 124 • An optional Border property. This property allows a client to 125 specify that the viewport of the CRTC is smaller than the active 126 display region described its mode. This is useful, for example, 127 for compensating for the overscan behavior of certain 128 televisions. 129 130Version 1.4 adds a new object called a provider object. A provider object 131represents a GPU or virtual device providing services to the X server. 132Providers have a set of abilities and a set of possible roles. 133 134Provider objects are used to control multi-GPU systems. Provider roles can 135be dynamically configured to provide support for: 136 137 1) Output slaving: plug in a USB device, but have its output rendered 138 using the main GPU. On some dual-GPU laptops, the second GPU isn't 139 connected to the LVDS panel, so we need to use the first GPU as an output 140 slave for the second GPU. 141 142 2) offload - For dual-GPU laptops, allow direct rendered applications to be run 143 on the second GPU and display on the first GPU. 144 145 3) GPU switching - Allow switching between two GPUs as the main screen 146 renderer. 147 148 4) multiple GPU rendering - This replaces Xinerama. 149 1501.5. Introduction to version 1.5 of the extension 151 152Version 1.5 adds an optional TILE property to outputs. 153 154 • An optional TILE property. 155 This property is used to denote individual tiles in a tiled monitor 156 configuration, as exposed via DisplayID v1.3. 157 158Version 1.5 adds monitors 159 160 • A 'Monitor' is a rectangular subset of the screen which represents 161 a coherent collection of pixels presented to the user. 162 163 • Each Monitor is associated with a list of outputs (which may be 164 empty). 165 166 • When clients define monitors, the associated outputs are removed from 167 existing Monitors. If removing the output causes the list for that 168 monitor to become empty, that monitor will be deleted. 169 170 • For active CRTCs that have no output associated with any 171 client-defined Monitor, one server-defined monitor will 172 automatically be defined of the first Output associated with them. 173 174 • When defining a monitor, setting the geometry to all zeros will 175 cause that monitor to dynamically track the bounding box of the 176 active outputs associated with them 177 178This new object separates the physical configuration of the hardware 179from the logical subsets of the screen that applications should 180consider as single viewable areas. 181 1821.5.1. Relationship between Monitors and Xinerama 183 184Xinerama's information now comes from the Monitors instead of directly 185from the CRTCs. The Monitor marked as Primary will be listed first. 186 1871.5.2. Clarification of Output lifetimes 188 189With dynamic connectors being a possibility with the introduction of 190DisplayPort multistream (MST), a lot of RandR clients can't handle the 191XID BadMatch when a RandR output disappears. This is to clarify that 192going forward the X server will not remove outputs dynamically, 193just mark them as disconnected. 194 1951.6. Introduction to version 1.6 of the extension 196 197Version 1.6 adds resource leasing and non desktop output management. 198 199 • A “Lease” is a collection of crtcs and outputs which are made 200 available to a client for direct access via kernel KMS and DRM 201 APIs. This is done by passing a suitable file descriptor back to 202 the client which has access to those resources. While leased, those 203 resources aren't used by the X server. 204 205 • A “non-desktop” output is a device which should not normally be 206 considered as part of the desktop environment. Head-mounted 207 displays and the Apple "Touch Bar" are examples of such 208 devices. A desktop environment should be able to discover which 209 outputs are connected to such devices and, by default, not present 210 normal desktop applications on them. This is done by having 211 RRGetOutputInfo report such devices as Disconnected while reporting 212 all other information about the device correctly. 213 2141.99 Acknowledgments 215 216Our thanks to the contributors to the design found on the xpert mailing 217list, in particular: 218 219Alan Hourihane for work on the early implementation 220Andrew C. Aitchison for help with the XFree86 DDX implementation 221Andy Ritger for early questions about how mergefb/Xinerama work with RandR 222Carl Worth for editing the specification and Usenix paper 223David Dawes for XFree86 DDX integration work 224Thomas Winischhofer for the hardware-accelerated SiS rotation implementation 225Matthew Tippett and Kevin Martin for splitting outputs and CRTCs to more 226fully expose what video hardware can do 227Dave Airlie for the 1.4.0 protocol changes and for working through the 228implications of MST monitors and encouraging the introduction of the 229'Monitor' concept. 230 231 ❧❧❧❧❧❧❧❧❧❧❧ 232 2332. Screen change model 234 235Screens may change dynamically, either under control of this extension, or 236due to external events. Examples include: monitors being swapped, pressing a 237button to switch from internal display to an external monitor on a laptop, 238or, eventually, the hotplug of a display card entirely on buses such as 239Cardbus or Express Card which permit hot-swap (which will require other work 240in addition to this extension). 241 242Since the screen configuration is dynamic and asynchronous to the client and 243may change at any time RandR provides mechanisms to ensure that your clients 244view is up to date with the configuration possibilities of the moment and 245enforces applications that wish to control the configuration to prove that 246their information is up to date before honoring requests to change the 247screen configuration (by requiring a timestamp on the request). 248 249Interested applications are notified whenever the screen configuration 250changes, providing the current size of the screen and subpixel order (see 251the Render extension [RENDER]), to enable proper rendering of subpixel 252decimated client text to continue, along with a time stamp of the 253configuration change. A client must refresh its knowledge of the screen 254configuration before attempting to change the configuration after a 255notification, or the request will fail. 256 257To avoid multiplicative explosion between orientation, reflection and sizes, 258the sizes are only those sizes in the normal (0) rotation. 259 260Rotation and reflection and how they interact can be confusing. In Randr, 261the coordinate system is rotated in a counter-clockwise direction relative 262to the normal orientation. Reflection is along the window system coordinate 263system, not the physical screen X and Y axis, so that rotation and 264reflection do not interact. The other way to consider reflection is to is 265specified in the "normal" orientation, before rotation, if you find the 266other way confusing. 267 268We expect that most clients and toolkits will be oblivious to changes to the 269screen structure, as they generally use the values in the connections Display 270structure directly. By toolkits updating the values on the fly, we believe 271pop-up menus and other pop up windows will position themselves correctly in 272the face of screen configuration changes (the issue is ensuring that pop-ups 273are visible on the reconfigured screen). 274 275 ❧❧❧❧❧❧❧❧❧❧❧ 276 2773. Data Types 278 279The subpixel order and transform data types are shared with the Render 280extension, and are documented there. 281 282The only datatype defined in the original extension is the screen size, 283defined in the normal (0 degree) orientation. Several more are added 284in later revisions. 285 286 ❧❧❧❧❧❧❧❧❧❧❧ 287 2884. Errors 289 290Errors are sent using core X error reports. 291 292Output 293 A value for an OUTPUT argument does not name a defined OUTPUT. 294CRTC 295 A value for a CRTC argument does not name a defined CRTC. 296Mode 297 A value for a MODE argument does not name a defined MODE. 298Provider 299 A value for a PROVIDER argument does not name a defined PROVIDER. 300Lease 301 A value for a LEASE argument does not name a defined LEASE 302 303 ❧❧❧❧❧❧❧❧❧❧❧ 304 3055. Protocol Types 306 307RRCONFIGSTATUS { Success 308 InvalidConfigTime 309 InvalidTime 310 Failed } 311 312 A value of type RRCONFIGSTATUS returned when manipulating the output 313 configuration or querying information from the server that has some 314 time-dependency. 315 316 InvalidConfigTime indicates that the supplied configuration 317 timestamp does not match the current X server configuration 318 timestamp. Usually this means that the output configuration has 319 changed since the timestamp was received by the application. 320 321 InvalidTime indicates that the supplied output reconfiguration time 322 is earlier than the most recent output reconfiguration request. 323 Generally this indicates that another application has reconfigured 324 the output using a later timestamp. 325 326 Failed is returned whenever the operation is unsuccessful for some 327 other reason. This generally indicates that the requested output 328 configuration is unsupported by the hardware. The goal is to make 329 these limitations expressed by the protocol, but when that isn't 330 possible it is correct to return this error value. If, as a 331 implementer, you find this error code required, please submit the 332 hardware constraints that exist so that a future version of the 333 extension can correctly capture the configuration constraints in 334 your system. 335 336ROTATION { Rotate_0 337 Rotate_90 338 Rotate_180 339 Rotate_270 340 Reflect_X 341 Reflect_Y } 342 343 These values are used both to indicate a set of allowed rotations 344 and reflections as well as to indicate a specific rotation and 345 reflection combination. 346 347RRSELECTMASK { RRScreenChangeNotifyMask 348 RRCrtcChangeNotifyMask (New in version 1.2) 349 RROutputChangeNotifyMask (New in version 1.2) 350 RROutputPropertyNotifyMask (New in version 1.2) 351 RRProviderChangeNotifyMask (New in version 1.4) 352 RRProviderPropertyNotifyMask (New in version 1.4) 353 RRResourceChangeNotifyMask (New in version 1.4) } 354 355SIZEID { CARD16 } 356 357MODE { XID or None } 358 359CRTC { XID } 360 361OUTPUT { XID } 362 363CONNECTION { Connected, Disconnected, UnknownConnection } 364 365 This value provides an indication of whether an output is actually 366 connected to a monitor or other presentation device. 367 368 369SCREENSIZE [ widthInPixels, heightInPixels: CARD16 370 widthInMillimeters, heightInMillimeters: CARD16 ] 371 372MODEFLAG { HSyncPositive 373 HSyncNegative 374 VSyncPositive 375 VSyncNegative 376 Interlace 377 DoubleScan 378 CSync 379 CSyncPositive 380 CSyncNegative 381 HSkewPresent 382 BCast 383 PixelMultiplex 384 DoubleClock 385 ClockDivideBy2 } 386 387MODEINFO [ id: MODE 388 name: STRING 389 width, height: CARD16 390 dotClock: CARD32 391 hSyncStart, hSyncEnd, hTotal, hSkew: CARD16 392 vSyncStart, vSyncEnd, vTotal: CARD16 393 modeFlags: SETofMODEFLAG ] 394 395REFRESH [ rates: LISTofCARD16 ] 396 397 ❧❧❧❧❧❧❧❧❧❧❧ 398 3995.1 Data Types defined by the Render extension 400 401These data types use the Render extension definitions; they are shown here 402only for convenience: 403 404SUBPIXELORDER { SubPixelUnknown 405 SubPixelHorizontalRGB 406 SubPixelHorizontalBGR 407 SubPixelVerticalRGB 408 SubPixelVerticalBGR 409 SubPixelNone } 410 411FIXED 32-bit value (top 16 are integer portion, bottom 16 are fraction) 412 413TRANSFORM [ 414 p11, p12, p13: FIXED 415 p21, p22, p23: FIXED 416 p31, p32, p33: FIXED 417 ] 418 419 ❧❧❧❧❧❧❧❧❧❧❧ 420 4215.5. Protocol Types added in version 1.4 of the extension 422 423PROVIDER { XID } 424 425PROVIDER_CAPS { SourceOutput, SinkOutput, SourceOffload, SinkOffload } 426 Capabilities for this provider: 427 SourceOutput: This device can source output buffers. 428 SinkOutput: This device can sink output buffers. 429 SourceOffload: This device can source offload buffers. 430 SinkOffload: This device can sink offload buffers. 431 432 ❧❧❧❧❧❧❧❧❧❧❧ 433 4345.6. Protocol Types added in version 1.5 of the extension 435 436MONITORINFO { name: ATOM 437 primary: BOOL 438 automatic: BOOL 439 x: INT16 440 y: INT16 441 width: CARD16 442 height: CARD16 443 width-in-millimeters: CARD32 444 height-in-millimeters: CARD32 445 outputs: LISTofOUTPUT } 446 447 ❧❧❧❧❧❧❧❧❧❧❧ 448 4495.7. Protocol Types added in version 1.6 of the extension 450 451LEASE { XID } 452 453 ❧❧❧❧❧❧❧❧❧❧❧ 454 4556. Extension Initialization 456 457The name of this extension is "RANDR". 458 459┌─── 460 RRQueryVersion 461 client-major-version: CARD32 462 client-minor-version: CARD32 463 ▶ 464 major-version: CARD32 465 minor-version: CARD32 466└─── 467 468 The client sends the highest supported version to the server 469 and the server sends the highest version it supports, but no 470 higher than the requested version. Major versions changes can 471 introduce incompatibilities in existing functionality, minor 472 version changes introduce only backward compatible changes. 473 It is the clients responsibility to ensure that the server 474 supports a version which is compatible with its expectations. 475 476 ❧❧❧❧❧❧❧❧❧❧❧ 477 4787. Extension Requests 479 480┌─── 481 RRSelectInput 482 window: WINDOW 483 enable: SETofRRSELECTMASK 484└─── 485 Errors: Window, Value 486 487 If 'enable' is RRScreenChangeNotifyMask, RRScreenChangeNotify events 488 will be sent when the screen configuration changes, either from 489 this protocol extension, or due to detected external screen 490 configuration changes. RRScreenChangeNotify may also be sent when 491 this request executes if the screen configuration has changed since 492 the client connected, to avoid race conditions. 493 494 New for version 1.2: 495 496 If 'enable' contains RRCrtcChangeNotifyMask, RRCrtcChangeNotify events 497 will be sent when the configuration for a CRTC associated with the 498 screen changes, either through this protocol extension or due to 499 detected external changes. RRCrtcChangeNotify may also be sent when 500 this request executes if the CRTC configuration has changed since 501 the client connected, to avoid race conditions. 502 503 If 'enable' contains RROutputChangeNotifyMask, RROutputChangeNotify 504 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 detected external changes. RROutputChangeNotify may also be sent when 507 this request executes if the output configuration has changed since the 508 client connected, to avoid race conditions. 509 510 If 'enable' contains RROutputPropertyNotifyMask, 511 RROutputPropertyNotify events will be sent when properties change on 512 this output. 513 514 New for version 1.4: 515 516 If 'enable' contains RRProviderChangeNotifyMask, 517 RRProviderChangeNotify events will be sent whenever the role for a 518 provider object has changed. 519 520 If 'enable' contains RRProviderPropertyNotifyMask, 521 RRProviderPropertyNotify events will be sent when properties change 522 on a provider object. 523 524 If 'enable' contains RRResourceChangeNotifyMask, 525 RRResourceChangeNotify events will be sent whenever the set of 526 available RandR resources associated with the screen has changed. 527 528┌─── 529 RRSetScreenConfig 530 window: WINDOW 531 timestamp: TIMESTAMP 532 config-timestamp: TIMESTAMP 533 size-id: SIZEID 534 rotation: ROTATION 535 rate: CARD16 536 ▶ 537 status: RRCONFIGSTATUS 538 new-timestamp: TIMESTAMP 539 config-timestamp: TIMESTAMP 540 root: WINDOW 541 subpixelOrder: SUBPIXELORDER 542└─── 543 Errors: Value, Match 544 545 If 'timestamp' is less than the time when the configuration was last 546 successfully set, the request is ignored and InvalidTime returned in 547 status. 548 549 If 'config-timestamp' is not equal to when the server's screen 550 configurations last changed, the request is ignored and 551 InvalidConfigTime returned in status. This could occur if the 552 screen changed since you last made a RRGetScreenInfo request, 553 perhaps by a different piece of display hardware being installed. 554 Rather than allowing an incorrect call to be executed based on stale 555 data, the server will ignore the request. 556 557 'rate' contains the desired refresh rate. If it is zero, the server 558 selects an appropriate rate. 559 560 This request may fail for other indeterminate reasons, in which case 561 'status' will be set to Failed and no configuration change will be 562 made. 563 564 This request sets the screen to the specified size, rate, rotation 565 and reflection. 566 567 When this request succeeds, 'status' contains Success and the 568 requested changes to configuration will have been made. 569 570 'new-time-stamp' contains the time at which this request was 571 executed. 572 573 'config-timestamp' contains the time when the possible screen 574 configurations were last changed. 575 576 'root' contains the root window for the screen indicated by the 577 window. 578 579 'subpixelOrder' contains the resulting subpixel order of the screen 580 to allow correct subpixel rendering. 581 582 Value errors are generated when 'rotation', 'rate' or 'size-id' 583 are invalid. 584 585┌─── 586 RRGetScreenInfo 587 window: WINDOW 588 ▶ 589 rotations: SETofROTATION 590 root: WINDOW 591 timestamp: TIMESTAMP 592 config-timestamp: TIMESTAMP 593 size-id: SIZEID 594 rotation: ROTATION 595 rate: CARD16 596 sizes: LISTofSCREENSIZE 597 refresh: LISTofREFRESH 598└─── 599 600 Errors: Window 601 602 RRGetScreenInfo returns information about the current and available 603 configurations for the screen associated with 'window'. 604 605 'rotations' contains the set of rotations and reflections supported 606 by the screen. 607 608 'root' is the root window of the screen. 609 610 'config-timestamp' indicates when the screen configuration 611 information last changed: requests to set the screen will fail 612 unless the timestamp indicates that the information the client 613 is using is up to date, to ensure clients can be well behaved 614 in the face of race conditions. 615 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 621 rate is unknown or on devices for which refresh is not relevant. 622 623 'sizes' is the list of possible frame buffer sizes (at the normal 624 orientation). Each size indicates both the linear physical size of 625 the screen and the pixel size. 626 627 'refresh' is the list of refresh rates for each size. Each element 628 of 'sizes' has a corresponding element in 'refresh'. An empty list 629 indicates no known rates, or a device for which refresh is not 630 relevant. 631 632 The default size of the screen (the size that would become the 633 current size when the server resets) is the first size in the 634 list. 635 6367.1. Extension Requests added in version 1.2 of the extension 637 638As introduced above, version 1.2 of the extension splits the screen size 639from the crtc and output configuration, permitting the subset of the screen 640presented by multiple outputs to be configured. As a separate notion, the 641size of the screen itself may be arbitrarily configured within a defined 642range. As crtcs and outputs are added and removed from the system, the set 643returned by the extension will change so that applications can detect 644dynamic changes in the display environment. 645 646┌─── 647 RRGetScreenSizeRange 648 window: WINDOW 649 ▶ 650 CARD16 minWidth, minHeight 651 CARD16 maxWidth, maxHeight 652└─── 653 Errors: Window 654 655 Returns the range of possible screen sizes. The screen may be set to 656 any size within this range. 657 658┌─── 659 RRSetScreenSize 660 window: WINDOW 661 width: CARD16 662 height: CARD16 663 width-in-millimeters: CARD32 664 height-in-millimeters: CARD32 665└─── 666 Errors: Window, Match, Value 667 668 Sets the screen to the specified size. 'width' and 'height' must be 669 within the range allowed by GetScreenSizeRanges, otherwise a Value 670 error results. All active monitors must be configured to display a 671 subset of the specified size, else a Match error results. 672 673 'width-in-millimeters' and 'height-in-millimeters' can be set to 674 reflect the physical size of the screen reported both through this 675 extension and the core protocol. They must be non-zero, or Value 676 error results. 677 678 If panning is enabled, the width and height of the panning and the 679 tracking areas are adapted to the new size and clamped afterwards. 680 Disabled panning axes remain disabled. 681 Panning borders are disabled if their requirements are no longer met 682 (see RRSetPanning). 683 684┌─── 685 RRGetScreenResources 686 window: WINDOW 687 ▶ 688 timestamp: TIMESTAMP 689 config-timestamp: TIMESTAMP 690 crtcs: LISTofCRTC 691 outputs: LISTofOUTPUT 692 modes: LISTofMODEINFO 693└─── 694 Errors: Window 695 696 RRGetScreenResources returns the list of outputs and crtcs connected 697 to the screen associated with 'window'. 698 699 'timestamp' indicates when the configuration was last set. 700 701 'config-timestamp' indicates when the configuration information last 702 changed. Requests to configure the output will fail unless the 703 timestamp indicates that the information the client is using is up 704 to date, to ensure clients can be well behaved in the face of race 705 conditions. 706 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 This request explicitly asks the server to ensure that the 714 configuration data is up-to-date wrt the hardware. If that requires 715 polling, this is when such polling would take place. If the 716 current configuration is all that's required, use 717 RRGetScreenResourcesCurrent instead. 718 719┌─── 720 RRGetOutputInfo 721 output: OUTPUT 722 config-timestamp: TIMESTAMP 723 ▶ 724 status: RRCONFIGSTATUS 725 timestamp: TIMESTAMP 726 crtc: CRTC 727 728 name: STRING 729 connection: CONNECTION 730 subpixel-order: SUBPIXELORDER 731 widthInMillimeters, heightInMillimeters: CARD32 732 crtcs: LISTofCRTC 733 clones: LISTofOUTPUT 734 modes: LISTofMODE 735 num-preferred: CARD16 736└─── 737 Errors: Output 738 739 RRGetOutputInfo returns information about the current and available 740 configurations 'output'. 741 742 If 'config-timestamp' does not match the current configuration 743 timestamp (as returned by RRGetScreenResources), 'status' is set to 744 InvalidConfigTime and the remaining reply data is empty. Otherwise, 745 'status' is set to Success. 746 747 'timestamp' indicates when the configuration was last set. 748 749 'crtc' is the current source CRTC for video data, or Disabled if the 750 output is not connected to any CRTC. 751 752 'name' is a UTF-8 encoded string designed to be presented to the 753 user to indicate which output this is. E.g. "S-Video" or "DVI". 754 755 'connection' indicates whether the hardware was able to detect a 756 device connected to this output. If the hardware cannot determine 757 whether something is connected, it will set this to 758 UnknownConnection. 759 760 'subpixel-order' contains the resulting subpixel order of the 761 connected device to allow correct subpixel rendering. 762 763 'widthInMillimeters' and 'heightInMillimeters' report the physical 764 size of the displayed area. If unknown, or not really fixed (e.g., 765 for a projector), these values are both zero. 766 767 'crtcs' is the list of CRTCs that this output may be connected to. 768 Attempting to connect this output to a different CRTC results in a 769 Match error. 770 771 'clones' is the list of outputs which may be simultaneously 772 connected to the same CRTC along with this output. Attempting to 773 connect this output with an output not in the 'clones' list 774 results in a Match error. 775 776 'modes' is the list of modes supported by this output. Attempting to 777 connect this output to a CRTC not using one of these modes results 778 in a Match error. 779 780 The first 'num-preferred' modes in 'modes' are preferred by the 781 monitor in some way; for fixed-pixel devices, this would generally 782 indicate which modes match the resolution of the output device. 783 784 Changes in version 1.6 of the protocol: 785 786 When a “non-desktop” device is connected, the 'connection' 787 field will report Disconnected but the remaining fields will 788 report information about the connected device. 789 790┌─── 791 RRListOutputProperties 792 output:OUTPUT 793 ▶ 794 atoms: LISTofATOM 795└─── 796 Errors: Output 797 798 This request returns the atoms of properties currently defined on 799 the output. 800 801 Changes in version 1.6 of the protocol: 802 803 When a “non-desktop” device is connected, the property list 804 will be correct for the device, even though RRGetOutputInfo 805 reports the device as disconnected. 806 807┌─── 808 RRQueryOutputProperty 809 output: OUTPUT 810 property: ATOM 811 ▶ 812 pending: BOOL 813 range: BOOL 814 immutable: BOOL 815 valid-values: LISTofINT32 816└─── 817 Errors: Name, Atom, Output 818 819 If the specified property does not exist for the specified output, 820 then a Name error is returned. 821 822 If 'pending' is TRUE, changes made to property values with 823 RRChangeOutputProperty will be saved in the pending property value 824 and be automatically copied to the current value on the next 825 RRSetCrtcConfig request involving the named output. If 'pending' is 826 FALSE, changes are copied immediately. 827 828 If 'range' is TRUE, then the valid-values list will contain 829 precisely two values indicating the minimum and maximum allowed 830 values. If 'range' is FALSE, then the valid-values list will contain 831 the list of possible values; attempts to set other values will 832 result in a Value error. 833 834 If 'immutable' is TRUE, then the property configuration cannot be 835 changed by clients. Immutable properties are interpreted by the X 836 server. 837 838 Changes in version 1.6 of the protocol: 839 840 When a “non-desktop” device is connected, the property information 841 will be correct for the device, even though RRGetOutputInfo 842 reports the device as disconnected. 843 844┌─── 845 RRConfigureOutputProperty 846 output: OUTPUT 847 property: ATOM 848 pending: BOOL 849 range: BOOL 850 valid-values: LISTofINT32 851└─── 852 Errors: Access, Name, Atom, Output 853 854 If the specified property is 'immutable', an Access error is 855 returned. 856 857 Otherwise, the configuration of the specified property is changed to 858 the values provided in this request. 859 860 If the specified property does not exist for the specified output, 861 it is created with an empty value and None type. 862 863┌─── 864 RRChangeOutputProperty 865 output: OUTPUT 866 property, type: ATOM 867 format: {8, 16, 32} 868 mode: { Replace, Prepend, Append } 869 data: LISTofINT8 or LISTofINT16 or LISTofINT32 870└─── 871 Errors: Alloc, Atom, Match, Value, Output 872 873 This request alters the value of the property for the specified 874 output. If the property is marked as a 'pending' property, only the 875 pending value of the property is changed. Otherwise, changes are 876 reflected in both the pending and current values of the property. 877 The type is uninterpreted by the server. The format specifies 878 whether the data should be viewed as a list of 8-bit, 16-bit, or 879 32-bit quantities so that the server can correctly byte-swap as 880 necessary. 881 882 If the mode is Replace, the previous property value is discarded. 883 If the mode is Prepend or Append, then the type and format must 884 match the existing property value (or a Match error results). If 885 the property is undefined, it is treated as defined with the correct 886 type and format with zero-length data. 887 888 For Prepend, the data is tacked on to the beginning of the existing 889 data, and for Append, it is tacked on to the end of the existing data. 890 891 This request generates a OutputPropertyNotify 892 893 The lifetime of a property is not tied to the storing client. 894 Properties remain until explicitly deleted, until the output is 895 destroyed, or until server reset (see section 10). 896 897 The maximum size of a property is server-dependent and may vary 898 dynamically. 899 900┌─── 901 RRDeleteOutputProperty 902 output: OUTPUT 903 property: ATOM 904└─── 905 Errors: Atom, Output 906 907 This request deletes the property from the specified window if the 908 property exists and generates a OutputPropertyNotify event unless 909 the property does not exist. 910 911┌─── 912 RRGetOutputProperty 913 output: OUTPUT 914 property: ATOM 915 type: ATOM or AnyPropertyType 916 long-offset, long-length: CARD32 917 delete: BOOL 918 pending: BOOL 919 ▶ 920 type: ATOM or None 921 format: {0, 8, 16, 32} 922 bytes-after: CARD32 923 value: LISTofINT8 or LISTofINT16 or LISTofINT32 924└─── 925 Errors: Atom, Value, Output 926 927 If the specified property does not exist for the specified output, 928 then the return type is None, the format and bytes-after are zero, 929 and the value is empty. The delete argument is ignored in this 930 case. 931 932 If the specified property exists but its type does not match the 933 specified type, then the return type is the actual type of the 934 property, the format is the actual format of the property (never 935 zero), the bytes-after is the length of the property in bytes (even 936 if the format is 16 or 32), and the value is empty. The delete 937 argument is ignored in this case. 938 939 If the specified property exists and either AnyPropertyType is 940 specified or the specified type matches the actual type of the 941 property, then the return type is the actual type of the property, 942 the format is the actual format of the property (never zero), and 943 the bytes-after and value are as follows, given: 944 945 N = actual length of the stored property in bytes 946 (even if the format is 16 or 32) 947 I = 4 × offset 948 T = N - I 949 L = MINIMUM(T, 4 × long-length) 950 A = N - (I + L) 951 952 If 'pending' is true, and if the property holds a pending value, 953 then the value returned will be the pending value of the property 954 rather than the current value. The returned value starts at byte 955 index I in the property (indexing from 0), and its length in bytes 956 is L. However, it is a Value error if long-offset is given such 957 that L is negative. The value of bytes-after is A, giving the 958 number of trailing unread bytes in the stored property. If delete 959 is True and the bytes-after is zero, the property is also deleted 960 from the output, and a RROutputPropertyNotify event is generated. 961 962 Changes in version 1.6 of the protocol: 963 964 When a “non-desktop” device is connected, the property value 965 will be correct for the device, even though RRGetOutputInfo 966 reports the device as disconnected. 967 968┌─── 969 RRCreateMode 970 window: WINDOW 971 modeinfo: MODEINFO 972 ▶ 973 mode: MODE 974└─── 975 Errors: Window, Name, Value 976 977 'modeinfo' provides a new mode for outputs on the screen 978 associated with 'window'. If the name of 'modeinfo' names an 979 existing mode, a Name error is returned. If some parameter of the 980 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 Errors: Mode, Access 989 990 The user-defined 'mode' is destroyed. 'mode' must name a mode 991 defined with RRCreateMode, else an Match error is returned. If 992 'mode' is in use by some CRTC or Output, then an Access error is 993 returned. 994 995┌─── 996 RRAddOutputMode 997 output: OUTPUT 998 mode: MODE 999└─── 1000 Errors: Output, Mode, Match 1001 1002 '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 RRDeleteOutputMode 1011 output: OUTPUT 1012 mode: MODE 1013└─── 1014 Errors: Output, Mode 1015 1016 'output' indicates which output is to be configured. 1017 1018 'mode' specifies which mode to delete. 'mode' must have been added 1019 with RRAddOutputMode, else an Access error is returned. 'mode' must 1020 not be active, else a Match error is returned. 1021 1022 This request generates OutputChangeNotify events. 1023 1024┌─── 1025 RRGetCrtcInfo 1026 crtc: CRTC 1027 config-timestamp: TIMESTAMP 1028 ▶ 1029 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 possible-outputs: LISTofOUTPUT 1039└─── 1040 1041 Errors: Window 1042 1043 RRGetCrtcInfo returns information about the current and available 1044 configurations for the specified crtc connected to the screen 1045 associated with 'window'. 1046 1047 If 'config-timestamp' does not match the current configuration 1048 timestamp (as returned by RRGetScreenResources), 'status' is set to 1049 InvalidConfigTime and the remaining reply data is empty. Otherwise, 1050 'status' is set to Success. 1051 1052 'timestamp' indicates when the configuration was last set. 1053 1054 'x' and 'y' indicate the position of this CRTC within the screen 1055 region. They will be set to 0 when the CRTC is disabled. 1056 1057 'width' and 'height' indicate the size of the area within the screen 1058 presented by this CRTC. This may be different than the size of the 1059 mode due to rotation, the projective transform, and the Border property 1060 described below. They will be set to 0 when the CRTC is disabled. 1061 1062 'mode' indicates which mode is active, or None indicating that the 1063 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 'outputs' is the list of outputs currently connected to this CRTC 1069 and is empty when the CRTC is disabled. 1070 1071 'rotations' contains the set of rotations and reflections supported 1072 by the CRTC. 1073 1074 'possible-outputs' lists all of the outputs which may be connected 1075 to this CRTC. 1076 1077┌─── 1078 RRSetCrtcConfig 1079 crtc: CRTC 1080 timestamp: TIMESTAMP 1081 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 Errors: Value, Match 1091 1092 If 'timestamp' is less than the time when the configuration was last 1093 successfully set, the request is ignored and InvalidTime returned in 1094 status. 1095 1096 If 'config-timestamp' is not equal to when the monitor's 1097 configuration last changed, the request is ignored and 1098 InvalidConfigTime returned in status. This could occur if the 1099 monitor changed since you last made a RRGetScreenInfo request, 1100 perhaps by a different monitor being connected to the machine. 1101 Rather than allowing an incorrect call to be executed based on stale 1102 data, the server will ignore the request. 1103 1104 'x' and 'y' contain the desired location within the screen for this 1105 monitor's content. 'x' and 'y' must be within the screen size, else 1106 a Value error results. 1107 1108 'mode' is either the desired mode or None indicating the CRTC should 1109 be disabled. If 'mode' is not one of these values, a Value 1110 error results. 'mode' must be valid for all of the configured outputs, 1111 else a Match error. 1112 1113 'rotation' contains the desired rotation along with which 1114 reflections should be enabled. The rotation and reflection values 1115 must be among those allowed for this monitor, else a Value error 1116 results. 1117 1118 'outputs' contains the set of outputs that this CRTC should be 1119 connected to. The set must be among the list of acceptable output 1120 sets for this CRTC or a Match error results. 1121 1122 If 'mode' is None, then 'outputs' must be empty, else a Match error 1123 results. Conversely, if 'mode' is not None, then 'outputs' must not be 1124 empty, else a Match error results. 1125 1126 This request may fail for other indeterminate reasons, in which case 1127 'status' will be set to Failed and no configuration change will be 1128 made. 1129 1130 This request sets the CRTC to the specified position, mode, rotation 1131 and reflection. The entire area of the CRTC must fit within the 1132 screen size, else a Match error results. As an example, rotating the 1133 screen so that a single CRTC fills the entire screen before and 1134 after may necessitate disabling the CRTC, resizing the screen, 1135 then re-enabling the CRTC at the new configuration to avoid an 1136 invalid intermediate configuration. 1137 1138 If panning is enabled, the width and height of the panning and the 1139 tracking areas are clamped to the new mode size. 1140 Disabled panning axes remain disabled. 1141 Panning borders are disabled if their requirements are no longer met 1142 (see RRSetPanning). 1143 1144 When this request succeeds, 'status' contains Success and the 1145 requested changes to configuration will have been made. 1146 1147 'new-time-stamp' contains the time at which this request was 1148 executed. 1149 1150┌─── 1151 RRGetCrtcGammaSize 1152 crtc: CRTC 1153 ▶ 1154 size: CARD16 1155└─── 1156 Errors: Crtc 1157 1158 This request returns the size of the gamma ramps used by 'crtc'. 1159 1160┌─── 1161 RRGetCrtcGamma 1162 crtc: CRTC 1163 ▶ 1164 red: LISTofCARD16 1165 green: LISTofCARD16 1166 blue: LISTofCARD16 1167└─── 1168 Errors: Crtc 1169 1170 This request returns the currently set gamma ramps for 'crtc'. All 1171 three lists will be the size returned by the RRGetCrtcGammaSize 1172 request. 1173 1174┌─── 1175 RRSetCrtcGamma 1176 crtc: CRTC 1177 red: LISTofCARD16 1178 green: LISTofCARD16 1179 blue: LISTofCARD16 1180└─── 1181 Errors: Crtc, Match 1182 1183 This request sets the gamma ramps for 'crtc'. All three lists 1184 must be the size returned by RRGetCrtcGammaSize else a Value error 1185 results. 1186 11877.2. Extension Requests added in version 1.3 of the extension 1188 1189┌─── 1190 RRGetScreenResourcesCurrent 1191 window: WINDOW 1192 ▶ 1193 timestamp: TIMESTAMP 1194 config-timestamp: TIMESTAMP 1195 crtcs: LISTofCRTC 1196 outputs: LISTofOUTPUT 1197 modes: LISTofMODEINFO 1198└─── 1199 Errors: Window 1200 1201 RRGetScreenResourcesCurrent returns the list of outputs and crtcs 1202 connected to the screen associated with 'window'. 1203 1204 'timestamp' indicates when the configuration was last set. 1205 1206 'config-timestamp' indicates when the configuration information last 1207 changed. Requests to configure the output will fail unless the 1208 timestamp indicates that the information the client is using is up 1209 to date, to ensure clients can be well behaved in the face of race 1210 conditions. 1211 1212 'crtcs' contains the list of CRTCs associated with the screen. 1213 1214 'outputs' contains the list of outputs associated with the screen. 1215 1216 'modes' contains the list of modes associated with the screen. 1217 1218 Unlike RRGetScreenResources, this merely returns the current 1219 configuration, and does not poll for hardware changes. 1220 1221┌─── 1222 RRSetCrtcTransform 1223 crtc: CRTC 1224 transform: TRANSFORM 1225 filter: STRING8 1226 values: LISTofFIXED 1227└─── 1228 Errors: Crtc, Match 1229 1230 This request provides a mechanism that is more general than the 1231 existing rotation and reflection values for describing the 1232 transformation from frame buffer image to crtc presentation. 1233 'transform' is a full 2D projective transformation from screen 1234 coordinate space to crtc coordinate space. This transformation is 1235 applied before the rotation and reflection values to compute the 1236 complete transform. 1237 1238 'filter' and 'values' specify a Render filter that may be used by the 1239 server when transforming data from frame buffer to crtc. 1240 1241 This request sets the transform to be used at the next 1242 RRSetCrtcConfig request execution; it does not cause any change to 1243 occur in the current configuration. 1244 1245 When a non-identity transformation is in use, the rectangle returned 1246 by RRGetCrtcInfo defines the bounding rectangle of the screen that is 1247 projected to the crtc. It is this projected rectangle which must be 1248 within the area of the screen when the mode is set. 1249 1250┌─── 1251 RRGetCrtcTransform 1252 crtc: CRTC 1253 ▶ 1254 pending-transform: TRANSFORM 1255 pending-filter: STRING8 1256 pending-values: LISTofFIXED 1257 current-transform: TRANSFORM 1258 current-filter: STRING8 1259 current-values: LISTofFIXED 1260└─── 1261 1262 This request returns the pending and current transforms for the 1263 specified CRTC. The pending transform will be the same as the current 1264 transform if no new pending transform has been set since the last call 1265 to RRSetCrtcConfig. 1266 1267┌─── 1268 RRGetPanning 1269 crtc: CRTC 1270 ▶ 1271 status: RRCONFIGSTATUS 1272 timestamp: TIMESTAMP 1273 left, top, width, height: CARD16 1274 track_left, track_top, track_width, track_height: CARD16 1275 border_left, border_top, border_right, border_bottom: INT16 1276└─── 1277 1278 Errors: Crtc 1279 1280 Version 1.3 adds panning support again. If multiple crtcs are active 1281 the panning behavior can be defined per crtc individually. 1282 RRGetPanning returns information about the currently set panning 1283 configuration for the specified crtc. If the CRTC does not support 1284 panning, all fields (except timestamp) will be 0. 1285 1286 'timestamp' indicates when the configuration was last set. 1287 1288 All other entries are explained for RRSetPanning. 1289 1290┌─── 1291 RRSetPanning 1292 crtc: CRTC 1293 timestamp: TIMESTAMP 1294 left, top, width, height: CARD16 1295 track_left, track_top, track_width, track_height: CARD16 1296 border_left, border_top, border_right, border_bottom: INT16 1297 ▶ 1298 status: RRCONFIGSTATUS 1299 new-timestamp: TIMESTAMP 1300└─── 1301 Errors: Crtc, Match 1302 1303 This request sets the panning parameters. As soon as panning is 1304 enabled, the CRTC position can change with every pointer move. 1305 RRCrtcChangeNotify events are sent to the clients requesting those. 1306 1307 If 'timestamp' is less than the time when the configuration was last 1308 successfully set, the request is ignored and InvalidTime returned in 1309 status. 1310 1311 ┌──┳━━━━━━━━━━━━━━┳─────┬ ─ ─ ─ ─ ─ ┐ 1312 │ ┃ CRTC ┃ │ 1313 │ ┃ ┃ │ │ 1314 │ ┃ X┃→ │ 1315 │ ┃ ┃ │ │ framebuffer 1316 │ ┗━━━━━━━━━━━━━━┛ │ 1317 │ │ │ 1318 │panning area │ 1319 └───────────────────────┴ ─ ─ ─ ─ ─ ┘ 1320 1321 'left', 'top', 'width', and 'height' contain the total panning area 1322 for this CRTC. 'width' has to be larger than or equal to the CRTC's 1323 width or 0, and 'left'+'width' must be within the screen size, else a 1324 Match error results. Equivalent restrictions for the height exist. 1325 'width' or 'height' set to 0 indicate that panning should be disabled 1326 on the according axis. Setting 'width'/'height' to the CRTC's 1327 width/height will disable panning on the X/Y axis as well, but 1328 RRSetScreenSize will silently enable panning if the screen size is 1329 increased. This does not happen if set to 0. 1330 1331 ┌────────┳━━━━━━━━━━━━━━┳ ─ ─ ─ ─ ─ ┐ 1332 │ ┃ CRTC ┃ 1333 │ ┃ ┃ │ 1334 │ ┃ ┃ 1335 │ ┃ ┃ │ tracking area 1336 │ ┗━━━━━━━━━━━━━━┫ X 1337 │ ↓ │ ↓ │ 1338 │panning area │ 1339 └───────────────────────┴ ─ ─ ─ ─ ─ ┘ 1340 1341 'track_left', 'track_top', 'track_width', and 'track_height' contain 1342 the pointer area for which the panning region is updated. For normal 1343 use cases it should enclose the panning area minus borders, and is 1344 typically set to either the panning area minus borders, or to the 1345 total screen size. If set to the total screen size, the CRTC will pan 1346 in the remaining axis even if the pointer is outside the panning area 1347 on a different CRTC, as shown in the figure above. If the pointer is 1348 outside the tracking area, the CRTC will not pan. Zero can be used as 1349 an alias for the total screen size. 1350 1351 ┌──┳━━━━━━━━━━━━━━┳────────────┐ 1352 │ ┃ CRTC ┃ │ 1353 │ ┃ ┃ │ 1354 │ ┃ ┃→ │ 1355 │ ┃ X←→┃ │ 1356 │ ┃ border_right │ 1357 │ ┗━━━━━━━━━━━━━━┛ │ 1358 │ │ 1359 │panning area │ 1360 └──────────────────────────────┘ 1361 1362 'border_left', 'border_top', 'border_right', and 'border_bottom' 1363 define the distances from the CRTC borders that will activate panning 1364 if the pointer hits them. If the borders are 0, the screen will pan 1365 when the pointer hits the CRTC borders (behavior of pre-RandR Xserver 1366 panning). If the borders are positive, the screen will pan when the 1367 pointer gets close to the CRTC borders, if they are negative, the 1368 screen will only pan when the pointer is already way past the CRTC 1369 borders. Negative values might confuse users and disable panning to 1370 the very edges of the screen. Thus they are discouraged. 1371 border_left + border_right has to be lower or equal than the CRTC's 1372 width, else a Match error results. An equivalent restriction for the 1373 height exists. 1374 1375 Screen size changes update the panning and the tracking areas to the 1376 new size. Both screen size changes and mode changes clamp these areas 1377 to the current CRTC size. In these cases panning borders are disabled 1378 if their requirements are no longer met. 1379 1380 When this request succeeds, 'status' contains Success and the 1381 requested changes to configuration will have been made. 1382 1383 'new-time-stamp' contains the time at which this request was 1384 executed. 1385 1386┌─── 1387 RRSetOutputPrimary 1388 window: WINDOW 1389 output: OUTPUT 1390└─── 1391 Errors: Match, Output, Window 1392 1393 RRSetOutputPrimary marks 'output' as the primary output for the 1394 screen with the same root window as 'window'. This output's CRTC 1395 will be sorted to the front of the list in Xinerama and RANDR 1396 geometry requests for the benefit of older applications. The 1397 default primary output is None, and None is a legal value to pass 1398 to RRSetOutputPrimary. This request is expected to be used by 1399 desktop environments to mark the screen that should hold the primary 1400 menu bar or panel. 1401 1402 As this changes the logical layout of the screen, ConfigureNotify 1403 and RRScreenChangeNotify will be generated on the appropriate root 1404 window when the primary output is changed by this call. This request 1405 also generates RROutputChangeNotify events on the outputs that gained 1406 and lost primary status. 1407 1408 If an output is disconnected asynchronously (eg. due to recabling), 1409 the primary status does not change, but RROutputChangeNotify events 1410 will be generated if the hardware is capable of detecting this; 1411 clients are expected to reconfigure if appropriate. 1412 1413 If an output is deleted (eg. due to device hotplug), the server will 1414 act as though None was passed to RRSetOutputPrimary, including 1415 generating the appropriate events. 1416 1417┌─── 1418 RRGetOutputPrimary 1419 window: WINDOW 1420 ▶ 1421 output: OUTPUT 1422└─── 1423 Errors: Window 1424 1425 RRGetOutputPrimary returns the primary output for the screen. 1426 1427 ❧❧❧❧❧❧❧❧❧❧❧ 1428 14297.4 Extension Requests added in version 1.4 of the extension. 1430 1431┌─── 1432 RRGetProviders 1433 window : WINDOW 1434 ▶ 1435 timestamp: TIMESTAMP 1436 providers: LISTofPROVIDER 1437└─── 1438 Errors: Window 1439 1440 RRGetProviders returns the list of providers connected to the screen 1441 associated with 'window'. 1442 1443 'timestamp' indicates when the configuration was last set. 1444 1445 'providers' contains the list of PROVIDERs associated with the 1446 screen. 1447 1448┌─── 1449 RRGetProviderInfo 1450 provider: PROVIDER 1451 ▶ 1452 capabilities: PROVIDER_CAPS 1453 name: STRING 1454 crtcs: LISTofCRTC 1455 outputs: LISTofOUTPUT 1456 associated_providers: LISTofPROVIDERS 1457 associated_provider_capability: LISTofPROVIDER_CAPS 1458└─── 1459 Errors: Provider 1460 1461 RRGetProviderInfo return information about the specified provider. 1462 The capabilities of the current provider are returned, along with 1463 the list of providers currently associated with this provider and 1464 the capability they are associated with. It also provides the list 1465 of crtcs and outputs that this provider is responsible for. 1466 1467 'name' is a UTF-8 encoded string to be presented to the user to 1468 indicate the device or driver supplied name. 1469 1470┌─── 1471 RRSetProviderOffloadSink 1472 provider: PROVIDER 1473 sink_provider: PROVIDER 1474 config-timestamp: TIMESTAMP 1475└─── 1476 Errors: Provider 1477 1478 RRSetOffloadSink sets the offload sink for this provider to the 1479 specified provider. 1480 1481┌─── 1482 RRSetProviderOutputSource 1483 provider: PROVIDER 1484 source_provider: PROVIDER 1485 config-timestamp: TIMESTAMP 1486└─── 1487 Errors: Provider 1488 1489 RRSetOutputSource sets the output source for this provider to the 1490 specified provider. 1491 1492┌─── 1493 RRListProviderProperties 1494 provider:PROVIDERS 1495 ▶ 1496 atoms: LISTofATOM 1497└─── 1498 Errors: Provider 1499 1500 This request returns the atoms of properties currently defined on 1501 the provider. 1502 1503┌─── 1504 RRQueryProviderProperty 1505 provider: PROVIDER 1506 property: ATOM 1507 ▶ 1508 pending: BOOL 1509 range: BOOL 1510 immutable: BOOL 1511 valid-values: LISTofINT32 1512└─── 1513 Errors: Name, Atom, Provider 1514 1515 If the specified property does not exist for the specified provider, 1516 then a Name error is returned. 1517 1518 If 'pending' is TRUE, changes made to property values with 1519 RRChangeProviderProperty will be saved in the pending property value 1520 and be automatically copied to the current value on the next 1521 RRSetCrtcConfig request on a crtc attached to that provider. 1522 If 'pending' is FALSE, changes are copied immediately. 1523 1524 If 'range' is TRUE, then the valid-values list will contain 1525 precisely two values indicating the minimum and maximum allowed 1526 values. If 'range' is FALSE, then the valid-values list will contain 1527 the list of possible values; attempts to set other values will 1528 result in a Value error. 1529 1530 If 'immutable' is TRUE, then the property configuration cannot be 1531 changed by clients. Immutable properties are interpreted by the X 1532 server. 1533 1534┌─── 1535 RRConfigureProviderProperty 1536 provider: PROVIDER 1537 property: ATOM 1538 pending: BOOL 1539 range: BOOL 1540 valid-values: LISTofINT32 1541└─── 1542 Errors: Access, Name, Atom, Provider 1543 1544 If the specified property is 'immutable', an Access error is 1545 returned. 1546 1547 Otherwise, the configuration of the specified property is changed to 1548 the values provided in this request. 1549 1550 If the specified property does not exist for the specified provider, 1551 it is created with an empty value and None type. 1552 1553┌─── 1554 RRChangeProviderProperty 1555 provider: PROVIDER 1556 property, type: ATOM 1557 format: {8, 16, 32} 1558 mode: { Replace, Prepend, Append } 1559 data: LISTofINT8 or LISTofINT16 or LISTofINT32 1560└─── 1561 Errors: Alloc, Atom, Match, Value, Provider 1562 1563 This request alters the value of the property for the specified 1564 provider. If the property is marked as a 'pending' property, only the 1565 pending value of the property is changed. Otherwise, changes are 1566 reflected in both the pending and current values of the property. 1567 The type is uninterpreted by the server. The format specifies 1568 whether the data should be viewed as a list of 8-bit, 16-bit, or 1569 32-bit quantities so that the server can correctly byte-swap as 1570 necessary. 1571 1572 If the mode is Replace, the previous property value is discarded. 1573 If the mode is Prepend or Append, then the type and format must 1574 match the existing property value (or a Match error results). If 1575 the property is undefined, it is treated as defined with the correct 1576 type and format with zero-length data. 1577 1578 For Prepend, the data is tacked on to the beginning of the existing 1579 data, and for Append, it is tacked on to the end of the existing data. 1580 1581 This request generates a ProviderPropertyNotify 1582 1583 The lifetime of a property is not tied to the storing client. 1584 Properties remain until explicitly deleted, until the provider is 1585 destroyed, or until server reset (see section 10). 1586 1587 The maximum size of a property is server-dependent and may vary 1588 dynamically. 1589┌─── 1590 RRDeleteProviderProperty 1591 provider: Provider 1592 property: ATOM 1593└─── 1594 Errors: Atom, Provider 1595 1596 This request deletes the property from the specified provider if the 1597 property exists and generates a ProviderPropertyNotify event unless 1598 the property does not exist. 1599 1600┌─── 1601 RRGetProviderProperty 1602 provider: PROVIDER 1603 property: ATOM 1604 type: ATOM or AnyPropertyType 1605 long-offset, long-length: CARD32 1606 delete: BOOL 1607 pending: BOOL 1608 ▶ 1609 type: ATOM or None 1610 format: {0, 8, 16, 32} 1611 bytes-after: CARD32 1612 value: LISTofINT8 or LISTofINT16 or LISTofINT32 1613└─── 1614 Errors: Atom, Value, Provider 1615 1616 If the specified property does not exist for the specified provider, 1617 then the return type is None, the format and bytes-after are zero, 1618 and the value is empty. The delete argument is ignored in this 1619 case. 1620 1621 If the specified property exists but its type does not match the 1622 specified type, then the return type is the actual type of the 1623 property, the format is the actual format of the property (never 1624 zero), the bytes-after is the length of the property in bytes (even 1625 if the format is 16 or 32), and the value is empty. The delete 1626 argument is ignored in this case. 1627 1628 If the specified property exists and either AnyPropertyType is 1629 specified or the specified type matches the actual type of the 1630 property, then the return type is the actual type of the property, 1631 the format is the actual format of the property (never zero), and 1632 the bytes-after and value are as follows, given: 1633 1634 N = actual length of the stored property in bytes 1635 (even if the format is 16 or 32) 1636 I = 4 × offset 1637 T = N - I 1638 L = MINIMUM(T, 4 × long-length) 1639 A = N - (I + L) 1640 1641 If 'pending' is true, and if the property holds a pending value, 1642 then the value returned will be the pending value of the property 1643 rather than the current value. The returned value starts at byte 1644 index I in the property (indexing from 0), and its length in bytes 1645 is L. However, it is a Value error if long-offset is given such 1646 that L is negative. The value of bytes-after is A, giving the 1647 number of trailing unread bytes in the stored property. If delete 1648 is True and the bytes-after is zero, the property is also deleted 1649 from the provider, and a RRProviderPropertyNotify event is generated. 1650 1651 1652 ❧❧❧❧❧❧❧❧❧❧❧ 1653 16547.5. Extension Requests added in version 1.5 of the extension. 1655 1656┌─── 1657 RRGetMonitors 1658 window : WINDOW 1659 get_active : BOOL 1660 ▶ 1661 timestamp: TIMESTAMP 1662 monitors: LISTofMONITORINFO 1663└─── 1664 Errors: Window 1665 1666 Returns the list of Monitors for the screen containing 1667 'window'. If 'get_active' is set it returns only active 1668 monitors (non-0x0 monitors). 'get_active' should always 1669 be set by toolkits, and not by configuration clients. 1670 1671 'timestamp' indicates the server time when the list of 1672 monitors last changed. 1673 1674┌─── 1675 RRSetMonitor 1676 window : WINDOW 1677 info: MONITORINFO 1678└─── 1679 Errors: Window, Output, Atom, Value 1680 1681 Create a new monitor. Any existing Monitor of the same name is deleted. 1682 1683 'name' must be a valid atom or an Atom error results. 1684 1685 'name' must not match the name of any Output on the screen, or 1686 a Value error results. 1687 1688 If 'info.outputs' is non-empty, and if x, y, width, height are all 1689 zero, then the Monitor geometry will be dynamically defined to 1690 be the bounding box of the geometry of the active CRTCs 1691 associated with them. 1692 1693 If 'name' matches an existing Monitor on the screen, the 1694 existing one will be deleted as if RRDeleteMonitor were called. 1695 1696 If an 'info.output' contains only the automatically generated default 1697 monitor, this is replaced by the new monitor. If the 'info.output' already 1698 contains a user-defined monitor, the new monitor will be added. 1699 This allows to have more than one monitor on an output (e.g. to split an 1700 output into multiple virtual monitors). 1701 1702 Only one monitor per screen may be primary. If 'info.primary' 1703 is true, then the primary value will be set to false on all 1704 other monitors on the screen. 1705 1706 RRSetMonitor generates a ConfigureNotify event on the root 1707 window of the screen. 1708 1709┌─── 1710 RRDeleteMonitor 1711 window : WINDOW 1712 name: ATOM 1713└─── 1714 Errors: Window, Atom, Value 1715 1716 Deletes the named Monitor. 1717 1718 'name' must be a valid atom or an Atom error results. 1719 1720 'name' must match the name of a Monitor on the screen, or a 1721 Value error results. 1722 1723 If the last user-defined monitor is removed from an 'info.output', 1724 the automatically generated default monitor will be restored. It is not 1725 possible to delete the automatically generated default monitor. 1726 1727 RRDeleteMonitor generates a ConfigureNotify event on the root 1728 window of the screen. 1729 1730 ❧❧❧❧❧❧❧❧❧❧❧ 1731 17327.6. Extension Requests added in version 1.6 of the extension. 1733 1734┌─── 1735 RRCreateLease 1736 window : WINDOW 1737 lid: LEASE 1738 crtcs: LISTofCRTC 1739 outputs: LISTofOUTPUT 1740 ▶ 1741 nfd: CARD8 1742 lease: FD 1743└─── 1744 Errors: IdChoice, Window, Access, Value, CRTC, Output 1745 1746 Creates a new Lease called 'lid' for the specified crtcs and 1747 outputs from the screen defined by 'window'. Returns a KMS/DRM 1748 file descriptor which can control the leased objects directly 1749 through the kernel. While leased, all resources will appear to 1750 be 'useless' to clients other than the leasing client as 1751 follows: 1752 1753 • Crtcs are reported as having no 'possible-outputs' and all 1754 other values reported as if the crtc were disabled. 1755 1756 • Outputs are reported as having no crtcs they can be 1757 connected to, no clones they can share a crtc with, will 1758 report a connection status of Disconnected, and will show 1759 the current crtc as if it were disabled. 1760 1761 The lease remains in effect until the file descriptor is 1762 closed, even if the client holding the lease disconnects from 1763 the X server. 1764 1765 Returns an Access error if any of the named resources are 1766 already leased to another client. 1767 1768┌─── 1769 RRFreeLease 1770 lid: LEASE 1771 terminate: BOOL 1772└─── 1773 Errors: Lease 1774 1775 Frees the reference to the lease 'lid'. If 'terminate' is 1776 true, then the lease is terminated and all leased resources 1777 returned to the X server. If 'terminate' is false, then the 1778 lease remains in effect, but the X server no longer has a name 1779 for it. 1780 1781 ❧❧❧❧❧❧❧❧❧❧❧ 17828. Extension Events 1783 1784Clients MAY select for ConfigureNotify on the root window to be 1785informed of screen changes. This may be advantageous if all your 1786client needs to know is the size of the root window, as it avoids 1787round trips to set up the extension. 1788 1789RRScreenChangeNotify is sent if RRSelectInput has requested it 1790whenever properties of the screen change, which may be due to external 1791factors, such as re-cabling a monitor, etc. 1792 1793┌─── 1794 RRScreenChangeNotify 1795 1796 rotation: ROTATION; new rotation 1797 sequenceNumber: CARD16 low 16 bits of request seq. number 1798 timestamp: TIMESTAMP time screen was changed 1799 configTimestamp: TIMESTAMP time config data was changed 1800 root: WINDOW root window of screen 1801 window: WINDOW window requesting notification 1802 size-id: SIZEID index of new SCREENSIZE 1803 subpixelOrder: SUBPIXELORDER order of subpixels 1804 widthInPixels: CARD16 width in pixels of the new SCREENSIZE 1805 heightInPixels: CARD16 height in pixels of the new SCREENSIZE 1806 widthInMillimeters: CARD16 width in mm of the new SCREENSIZE 1807 heightInMillimeters: CARD16 height in mm of the new SCREENSIZE 1808└─── 1809 This event is generated whenever the screen configuration is changed 1810 and sent to requesting clients. 'timestamp' indicates when the 1811 screen configuration was changed. 'configTimestamp' says when the 1812 last time the configuration was changed. 'root' is the root of the 1813 screen the change occurred on, 'window' is window selecting for this 1814 event. 'size-id' contains the index of the current size. 1815 1816 This event is sent whenever the screen's configuration changes 1817 or if a new screen configuration becomes available that was 1818 not available in the past. In this case (config-timestamp in 1819 the event not being equal to the config-timestamp returned in 1820 the last call to RRGetScreenInfo), the client MUST call 1821 RRGetScreenInfo to update its view of possible screen 1822 configurations to have a correct view of possible screen 1823 organizations. 1824 1825 Clients which select screen change notification events may be 1826 sent an event immediately if the screen configuration was 1827 changed between when they connected to the X server and 1828 selected for notification. This is to prevent a common race 1829 that might occur on log-in, where many applications start up 1830 just at the time when a display manager or log in script might 1831 be changing the screen size or configuration. 1832 1833 Note that the sizes in this event reflect the new SCREENSIZE and 1834 thus will appear rotated by the 'rotation' parameter from the sizes 1835 of the screen itself. In other words, when rotation is 90 or 270, 1836 widthInPixels in this event will be the same as the height value 1837 from a ConfigureNotify that reflects the same size change. This 1838 will probably confuse developers. 1839 18408.1 Events added in version 1.2 of the RandR extension 1841 1842┌─── 1843 RROutputChangeNotify: 1844 timestamp: TIMESTAMP time screen was reconfigured 1845 config-timestamp: TIMESTAMP time available config data was changed 1846 window: WINDOW window requesting notification 1847 output: OUTPUT output affected by change 1848 crtc: CRTC connected CRTC or None 1849 mode: MODE mode in use on CRTC or None 1850 connection: CONNECTION connection status 1851└─── 1852 1853 This event is generated whenever the available output configurations 1854 have changed and is sent to requesting clients. 'timestamp' 1855 indicates when the crtc configuration was changed by a client. 1856 'config-timestamp' says when the last time the available 1857 configurations changed. 'root' is the root of the screen the change 1858 occurred on, 'window' is window selecting for this event. The 1859 precise change can be detected by examining the new state of the 1860 system. 1861 1862 Changes in version 1.6 of the protocol: 1863 1864 When a “non-desktop” device is connected, this event will be 1865 delivered when the connection status of the output changes, 1866 however the 'connection' value will be set to 'Disconnected'. 1867 1868┌─── 1869 RROutputPropertyNotify: 1870 window: WINDOW window requesting notification 1871 output: OUTPUT output affected by change 1872 atom: ATOM affected property 1873 time: TIMESTAMP time property was changed 1874 subpixel-order: SUBPIXELORDER order of subpixels 1875 state: { NewValue, Deleted } new property state 1876└─── 1877 1878 This event is reported to clients selecting RROutputPropertyChange 1879 on the window and is generated with state NewValue when a property 1880 of the window is changed using RRChangeOutputProperty even when 1881 adding zero-length data and when replacing all or part of a property 1882 with identical data. It is generated with state Deleted when a 1883 property of the window is deleted using either 1884 RRDeleteOutputProperty or RRGetOutputProperty. The timestamp 1885 indicates the server time when the property was changed. 1886 1887┌─── 1888 RRCrtcChangeNotify 1889 timestamp: TIMESTAMP time monitor was changed 1890 window: WINDOW window requesting notification 1891 crtc: CRTC CRTC which changed 1892 mode: MODE new mode 1893 rotation: ROTATION; new rotation 1894 x: INT16 x position of CRTC within screen 1895 y: INT16 y position of CRTC within screen 1896 width: CARD16 width of new configuration 1897 height: CARD16 height of new configuration 1898└─── 1899 This event is generated whenever the CRTC configuration is changed 1900 and sent to requesting clients. 'timestamp' indicates when the 1901 CRTC configuration was changed. 'window' is window selecting for this 1902 event. 'mode' is the new mode, or None if the crtc is disabled. 1903 'x' and 'y' mark the location in the screen where this CRTC 1904 is reading data. 'width' and 'height' indicate the size of the 1905 CRTC viewport, which is the mode size adjusted by the optional 1906 Border output property described below. 'x', 'y, 'width' and 1907 'height' are all zero when 'mode' is None. 1908 1909 This event is sent whenever the monitor's configuration changes 1910 or if a new monitor configuration becomes available that was 1911 not available in the past. In this case, the client MUST call 1912 RRGetCrtcInfo to update its view of possible monitor 1913 configurations to have a correct view of possible monitor 1914 organizations. 1915 1916 Clients which select monitor change notification events may be 1917 sent an event immediately if the monitor configuration was 1918 changed between when they connected to the X server and 1919 selected for notification. This is to prevent a common race 1920 that might occur on log-in, where many applications start up 1921 just at the time when a display manager or log in script might 1922 be changing the monitor size or configuration. 1923 19248.2 Events added in version 1.4 of the RandR extension 1925 1926┌─── 1927 RRProviderChangeNotify: 1928 timestamp: TIMESTAMP time screen was reconfigured 1929 window: WINDOW window requesting notification 1930 provider: PROVIDER provider affected by change 1931└─── 1932 1933 This event is generated whenever the role for a provider has changed 1934 and is sent to requesting clients. 'timestamp' indicates when the 1935 provider configuration was changed by a client. 'window' is the 1936 window selecting for this event. The precise change can be detected 1937 by examining the new state of the system. 1938 1939┌─── 1940 RRProviderPropertyNotify: 1941 window: WINDOW window requesting notification 1942 provider: PROVIDER provider affected by change 1943 atom: ATOM affected property 1944 time: TIMESTAMP time property was changed 1945 state: { NewValue, Deleted } new property state 1946└─── 1947 1948 This event is reported to clients selecting RRProviderPropertyChange 1949 on the window and is generated with state NewValue when a property 1950 of the window is changed using RRChangeProviderProperty even when 1951 adding zero-length data and when replacing all or part of a property 1952 with identical data. It is generated with state Deleted when a 1953 property of the window is deleted using either 1954 RRDeleteProviderProperty or RRGetProviderProperty. The timestamp 1955 indicates the server time when the property was changed. 1956 1957┌─── 1958 RRResourceChangeNotify: 1959 window: WINDOW window requesting notification 1960 time: TIMESTAMP time property was changed 1961└─── 1962 1963 This event is reported to clients selecting RRResourceChange 1964 on the window and is generated whenever the set of available 1965 RandR resources associated with the screen has changed, either 1966 created or destroyed. Querying the list of available resources 1967 with RRGetScreenResources and RRGetProviders will return the new set. 1968 19698.3 Events added in version 1.6 of the RandR extension 1970 1971┌─── 1972 RRLeaseNotify: 1973 timestamp : TIMESTAMP time screen was reconfigured 1974 window : WINDOW window requesting notification 1975 lease : LEASE lease 1976 created : BOOL created/destroyed indicator 1977└─── 1978 1979 This event is generated whenever a lease has been created or 1980 destroyed and is sent to requesting clients. 'timestamp' 1981 indicates when the change happened. 'window' is the window 1982 selecting for this event. 1983 1984 ❧❧❧❧❧❧❧❧❧❧❧ 1985 19869. Properties 1987 1988Properties are used for output specific parameters, and for announcing 1989static or rarely changing data. Announced data is typically 1990immutable. Properties are also used for evaluating new parameters 1991before adding them to the RandR protocol. 1992 1993The following properties are hereby declared official, and drivers SHOULD 1994prefix driver specific properties with '_', unless they are planned to be 1995added to this specification. List values, that are not declared by the table 1996below, and will remain driver specific or are not planned to be added to this 1997specification, SHOULD be prefixed with "_" as well in order to avoid name 1998space or semantics clashes with future extensions of these values. 1999 2000Beginning with version 1.3 of the RandR extension, certain properties 2001are mandatory and MUST be provided by implementations. Earlier 2002versions of the RandR extension MAY provide these properties as well, 2003as long as the semantics are not altered. Clients SHOULD fall back 2004gracefully to lower version functionality, though, if the driver 2005doesn't handle a mandatory property correctly. 2006 2007Changes in version 1.6 of the protocol: 2008 2009When a “non-desktop” device is connected, the property information 2010will be correct for the device, even though RRGetOutputInfo 2011reports the device as disconnected. The “non-desktop” property will be 2012set to 1 for such devices and not present on other devices. 2013 20149.1 Known properties 2015 2016 "Backlight" aka RR_PROPERTY_BACKLIGHT 2017 Type: INTEGER 2018 Format: 32 2019 Num. items: 1 2020 Flags: - 2021 Range/List: 0-x (driver specific) 2022 2023 This property controls the brightness on laptop panels and equivalent 2024 displays with a backlight controller. The driver specific maximum 2025 value MUST turn the backlight to full brightness, 1 SHOULD turn the 2026 backlight to minimum brightness, 0 SHOULD turn the backlight off. 2027 2028 "CloneList" aka RR_PROPERTY_CLONE_LIST 2029 Type: ATOM 2030 Format: 32 2031 Num. items: 2*n 2032 Flags: Immutable 2033 Range/List: 0- 2034 2035 Some combinations of outputs on some cards cannot be served 2036 independently from each other, because they are wired up to the same 2037 encoder outputs. 2038 This property lists all output + signal format pairs that are 2039 driven together with this output, and thus can only be programmed in 2040 clone mode with the same CRTC. 2041 This property MUST be symmetric, but may change with changing signal 2042 format. I.e. if the property for DVI-1/VGA specifies VGA-1/VGA to be 2043 cloned, VGA-1/VGA has to list DVI-1/VGA as well. 2044 Outputs / format pairs listed in this property MUST be included in the 2045 CompatibilityList. 2046 2047 "CompatibilityList" aka RR_PROPERTY_COMPATIBILITY_LIST 2048 Type: ATOM 2049 Format: 32 2050 Num items: 2*n 2051 Flags: Immutable 2052 Range/List: 0- 2053 2054 Some combinations of outputs on some cards cannot be served at all, 2055 because the according encoder is only capable of driving one output at 2056 a time. 2057 This property lists all output + signal format pairs that can be 2058 driven together with this output. NULL atoms specify any output / any 2059 signal format, respectively. 2060 This property MUST be symmetric, but may change with changing signal 2061 format. I.e. if the property for DVI-1/TMDS specifies VGA-1/VGA to be 2062 available, VGA-1/VGA has to list DVI-1/TMDS as well. 2063 2064 "ConnectorNumber" aka RR_PROPERTY_CONNECTOR_NUMBER 2065 Type: INTEGER 2066 Format: 32 2067 Num items: 1 2068 Flags: Immutable, Static 2069 Range/List: 0- 2070 2071 Outputs that route their signal to the same connector MUST 2072 have the same connector number. Outputs with the same 2073 connector number MUST route their signal to the same 2074 connector, except if it is 0, which indicates unknown 2075 connectivity. 1 is called the primary connector, 2 the 2076 secondary. 3 is typically a TV connector, but that is completely 2077 driver / hardware dependent. 2078 Outputs with the same connector number SHOULD have the same 2079 connector type. Meaning and client behavior for mismatching 2080 connector types is undefined at the moment. 2081 2082 "ConnectorType" aka RR_PROPERTY_CONNECTOR_TYPE 2083 Type: ATOM 2084 Format: 32 2085 Num items: 1 2086 Flags: Immutable, Static 2087 Range/List: unknown VGA DVI DVI‐I DVI‐A DVI‐D HDMI Panel 2088 TV TV-Composite TV-SVideo TV-Component 2089 TV-SCART TV-C4 DisplayPort 2090 2091 Connector type, as far as known to the driver. 2092 Values with dashes (TV‐Composite) describe more specific versions of 2093 the base values (TV). The former SHOULD be used if the connector is 2094 not capable of producing other signal formats. The later SHOULD be 2095 used if the exact connector is unknown, or the connector is a 2096 multi‐format connector that is not described otherwise. DVI, for 2097 instance, SHOULD be handled like a DVI‐I connector, unless additional 2098 information is available to the user agent. PANEL describes 2099 laptop‐internal (normally LVDS) displays. TV, TV‐SCART, TV‐Component, 2100 and TV‐C4 with signal format VGA are valid combinations and describe 2101 RGB TV signals. 2102 2103 "EDID" aka RR_PROPERTY_RANDR_EDID 2104 Type: INTEGER 2105 Format: 8 2106 Num items: n 2107 Flags: Immutable 2108 Range/List: - 2109 2110 Raw EDID data from the device attached to the according 2111 output. Should include main EDID data and all extension 2112 blocks. Previously known as EdidData. 2113 2114 “non-desktop” aka RR_PROPERTY_NON_DESKTOP 2115 Type: INTEGER 2116 Format: 32 2117 Num items: 1 2118 Flags Immutable 2119 Range/List: 0-1 2120 2121 Indicates whether the device attached to this output should not 2122 be considered part of the normal desktop. When set to 0 or not 2123 present, the output should be presented as part of the 2124 desktop. 2125 2126 When set to 1, the output should not be presented as part of 2127 the desktop. To not present an output as part of the desktop, 2128 the normal desktop environment should not be shown on this 2129 output, nor should desktop applications be positioned on it. 2130 2131 When set to 1, RRGetOutputInfo will always report connection status 2132 Disconnected, but RROutputChangeNotify events will still be 2133 delivered when the connection status changes and all other 2134 information about the output and connected device will be 2135 reported correctly. 2136 2137 "SignalFormat" aka RR_PROPERTY_SIGNAL_FORMAT 2138 Type: ATOM 2139 Format: 32 2140 Num items: 1 2141 Flags: - 2142 Range/List: unknown VGA TMDS LVDS Composite Composite-PAL 2143 Composite-NTSC Composite-SECAM SVideo 2144 Component DisplayPort 2145 2146 Signal format / physical protocol format that is used for the 2147 specified output. valid-values lists all possible formats on this 2148 output, which SHOULD be a subset of the list above and MUST be static. 2149 Values with dashes (Composite-PAL) describe more specific versions of 2150 the base values (Composite) and SHOULD be used if known to the driver. 2151 A driver MAY change this property of an output if the underlying 2152 hardware indicates a protocol change (e.g. TV formats). Clients are 2153 allowed to change the signal format in order to select a different 2154 signal format (e.g. Composite etc.) or physical protocol (e.g. VGA or 2155 TMDS on DVI-I). 2156 Laptop panels SHOULD not be detected with this property, but rather by 2157 ConnectorType. 2158 2159 "SignalProperties" aka RR_PROPERTY_SIGNAL_FORMAT 2160 Type: ATOM 2161 Format: 32 2162 Num items: n 2163 Flags: - 2164 Range/List: For Composite signals: 2165 NTSC NTSC-M NTSC-J NTSC-N NTSC-4.43 NTSC-film 2166 PAL PAL-B PAL-G PAL-H PAL-H PAL-I PAL-M PAL-D 2167 PAL-N PAL-Nc PAL-L PAL-60 2168 SECAM SECAM-L SECAM-B SECAM-G SECAM-D SECAM-K 2169 SECAM-H SECAM-K 2170 For TMDS signals: 2171 SingleLink DualLink 2172 For DisplayPort signals: 2173 Lane1 Lane2 Lane4 LowSpeed HiSpeed 2174 2175 Properties of the signal format that is currently used for the 2176 specified output. valid-values lists all possible properties on this 2177 output, which SHOULD be a subset of the list above. It will change if 2178 SignalFormat changes. Multiple properties are allowed. 2179 Values with dashes (PAL-B) describe more specific versions of the base 2180 values (PAL) and SHOULD be used if known to the driver. A driver MAY 2181 change this property of an output if the underlying hardware indicates 2182 a signal change (e.g. TV formats). Clients are allowed to change the 2183 properties in order to select a different signal subformat. 2184 2185 "Border" aka RR_PROPERTY_BORDER 2186 Type: CARDINAL 2187 Format: 16 2188 Num items: 0, 1, 2, or 4 2189 Flags: Immutable 2190 Range/List: 0- 2191 2192 This property is a list of integers specifying adjustments for the edges 2193 of the displayed image. How this property is applied depends on the 2194 number of elements in the list: 2195 2196 0 = No border is applied 2197 1 = A border of Border[0] is applied to all four sides of the image. 2198 2 = A border of Border[0] is applied to the left and right sides of 2199 the image, and a border of Border[1] is applied to the top and 2200 bottom. 2201 4 = The border dimensions are as follows: 2202 Border[0]: left 2203 Border[1]: top 2204 Border[2]: right 2205 Border[3]: bottom 2206 2207 Note that how many configuration dimensions are actually supported is 2208 specified by the BorderDimensions property described below. If more than 2209 BorderDimensions values are specified, the extra values are ignored. 2210 2211 These border dimensions shrink the region of pixels displayed by the 2212 CRTC by the corresponding number of rows or columns, and is applied 2213 after the CRTC transform. For example, a mode with a 1920x1080 active 2214 region, border dimensions of [ 10, 20, 30, 40 ], and a ½x scaling 2215 transform would display a rectangle of 940x510 pixels from the scanout 2216 pixmap scaled to 1880x1020 raster pixels positioned at (10, 20) in 2217 display raster space. 2218 2219 Raster pixels in the border are black. 2220 2221 This property is created with pending == TRUE, so changes are not 2222 applied immediately and instead take effect at the next RRSetCrtcConfig. 2223 2224 If multiple outputs with different border settings are bound to the same 2225 CRTC when the configuration is changed, the behavior is undefined. 2226 2227 If the length of the property is less than four when the CRTC is 2228 configured, the missing values are assumed to be zero. If the length is 2229 greater than four, the extra values are ignored. 2230 2231 If the width of the mode is less than or equal to the sum of the left 2232 and right borders, then the left and right border settings are ignored. 2233 Likewise, if the height of the mode is less than or equal to the sum of 2234 the top and bottom borders, the top and bottom borders are ignored. 2235 2236 "BorderDimensions" aka RR_PROPERTY_BORDER_DIMENSIONS 2237 Type: CARDINAL 2238 Format: 8 2239 Num items: 1 2240 Flags: Immutable, Static 2241 Range/List: 0, 1, 2, or 4 2242 2243 This property lists how many border adjustment parameters can actually 2244 be used: 2245 2246 0 = no borders are supported 2247 1 = a single border value is applied to all four sides of the image 2248 2 = left/right and top/bottom borders can be specified independently 2249 4 = all four borders can be specified independently 2250 2251 "GUID" aka RR_PROPERTY_GUID 2252 Type: INTEGER 2253 Format: 8 2254 Num items: 16 2255 Flags: Immutable 2256 Range/List: - 2257 2258 Some display devices, such as DisplayPort 1.2 devices, have globally 2259 unique identifiers. When such an identifier is available, this property 2260 contains its raw bytes. 2261 2262 "TILE" aka RR_PROPERTY_RANDR_TILE 2263 Type: INTEGER 2264 Format: 32 2265 Num items: 8 2266 Flags: Immutable 2267 Range/List: - 2268 2269 Tile monitors have an array of values describing the tiling, 2270 based on DisplayID v1.3 2271 2272 The 8 elements are: 2273 0: group id - The tile group identifier 2274 1: flags - flags for tile group 2275 0x1 = single monitor enclosure 2276 2: number of horizontal tiles in tile group 2277 3: number of vertical tiles in tile group 2278 4: horizontal tile location for this tile 2279 5: vertical tile location for this tile 2280 6: horizontal tile size for this tile 2281 7: vertical tile size for this tile 2282 22839.2 Properties introduced with version 1.2 of the RandR extension 2284 2285Property Immutable Mandatory since 2286──────── ───────── ─────────────── 2287EDID yes n/a 2288 2289EDID is provided by the RandR frontend, thus not driver specific. 2290 2291 22929.3 Properties introduced with version 1.3 of the RandR extension 2293 2294Property Immutable Mandatory since 2295──────── ───────── ─────────────── 2296CloneList yes not mandatory 2297CompatibilityList yes not mandatory 2298ConnectorNumber yes: static not mandatory 2299ConnectorType yes: static RandR 1.3 2300SignalFormat no RandR 1.3 2301SignalProperties no not mandatory 2302 23039.4 Properties introduced with version 1.3.1 of the RandR extension 2304 2305Property Immutable Mandatory since 2306──────── ───────── ─────────────── 2307Backlight no not mandatory 2308 23099.5 Properties introduced with version 1.4.0 of the RandR extension 2310 2311Property Immutable Mandatory since 2312──────── ───────── ─────────────── 2313Border yes not mandatory 2314BorderDimensions yes: static not mandatory 2315 23169.6 Properties introduced with version 1.4.1 of the RandR extension 2317 2318Property Immutable Mandatory since 2319──────── ───────── ─────────────── 2320GUID yes not mandatory 2321 23229.7 Properties introduced with version 1.5 of the RandR extension 2323 2324Property Immutable Mandatory since 2325──────── ───────── ─────────────── 2326TILE yes not mandatory 2327 23289.8 Properties introduced with version 1.6 of the RandR extension 2329 2330Property Immutable Mandatory since 2331──────── ───────── ─────────────── 2332non-desktop yes not mandatory 2333 2334 ❧❧❧❧❧❧❧❧❧❧❧ 2335 233610. Extension Versioning 2337 2338The RandR extension was developed in parallel with the implementation 2339to ensure the feasibility of various portions of the design. As 2340portions of the extension are implemented, the version number of the 2341extension has changed to reflect the portions of the standard provided. 2342This document describes the version 1.4 of the specification, the 2343partial implementations have version numbers less than that. Here's a 2344list of what each version provided: 2345 2346 0.0: This prototype implemented resize and rotation in the 2347 TinyX server Used approximately the protocol described in 2348 the Usenix paper. Appeared in the TinyX server in 2349 XFree86 4.2, but not in the XFree86 main server. 2350 2351 0.1: Added subpixel order, added an event for subpixel order. 2352 This version was never checked in to XFree86 CVS. 2353 2354 1.0: Implements resize, rotation, and reflection. Implemented 2355 both in the XFree86 main server (size change only at this 2356 date), and fully (size change, rotation, and reflection) 2357 in XFree86's TinyX server. 2358 2359 1.1: Added refresh rates 2360 2361 1.2: Separate screens from CRTCs and outputs, switch to full VESA 2362 modes 2363 2364 1.3: Added cheap version of RRGetScreenResources. Added CRTC 2365 transformations. Added panning. Added primary outputs. 2366 Added standard properties. 2367 2368 1.4: Added provider objects for handling multi-GPU systems. 2369 2370 1.5: Added Monitors 2371 2372 1.6: Added Leases and non-desktop output information. 2373 2374Compatibility between 0.0 and 1.0 was *NOT* preserved, and 0.0 clients 2375will fail against 1.0 servers. The wire encoding op-codes were 2376changed for GetScreenInfo to ensure this failure in a relatively 2377graceful way. Version 1.1 servers and clients are cross compatible with 23781.0. Version 1.1 is considered to be stable and we intend upward 2379compatibility from this point. Version 1.2 offers an extended model of the 2380system with multiple output support. Version 1.3 adds a cheap version of 2381GetScreenResources to avoid expensive DDC operations, CRTC transformations, 2382panning, and the primary output concept. Versions 1.2 through 1.6 are 2383backward-compatible with 1.1. 2384 2385 ❧❧❧❧❧❧❧❧❧❧❧ 2386 238711. Relationship with other extensions 2388 2389Two other extensions have a direct relationship with this extension. This 2390section attempts to explain how these three are supposed to work together. 2391 239211.1 XFree86-VidModeExtension 2393 2394XFree86-VidModeExtension changes the configuration of a single monitor 2395attached to the screen without changing the configuration of the screen 2396itself. It provides the ability to specify new mode lines for the server to 2397use along with selecting among existing mode lines. As it uses screen 2398numbers instead of window identifiers, it can be used to affect multiple 2399monitors in a single-screen Xinerama configuration. However, the association 2400between screen numbers and root windows in a multi-Screen environment is not 2401defined by the extension. Version 2.0 of this extension added the ability to 2402adjust the DAC values in a TrueColor server to modify the brightness curves 2403of the display. 2404 2405All of the utility of this extension is subsumed by RandR version 1.2, RandR 2406should be used in preference to XFree86-VidModeExtension where both are 2407present. 2408 240911.2 Xinerama 2410 2411Xinerama provides a mechanism for describing the relationship between the 2412overall screen display and monitors placed within that area. As such, it 2413provides the query functionality of RandR 1.2 without any of the 2414configuration functionality. Applications using Xinerama to discover 2415monitor geometry can continue to do so, with the caveat that they will not be 2416informed of changes when they occur. However, Xinerama configuration data 2417will be updated, so applications selecting for RandR notification and 2418re-querying the configuration with the Xinerama extension will get updated 2419information. It is probably better to view RandR as a superset of Xinerama 2420at this point and use it in preference to Xinerama where both are present. 2421 2422 ❧❧❧❧❧❧❧❧❧❧❧ 2423 2424Appendix A. Protocol Encoding 2425 2426Syntactic Conventions 2427 2428This document uses the same syntactic conventions as the core X 2429protocol encoding document. 2430 2431A.1 Common Types 2432 2433┌─── 2434 ROTATION 2435 0x0001 Rotate_0 2436 0x0002 Rotate_90 2437 0x0004 Rotate_180 2438 0x0008 Rotate_270 2439 0x0010 Reflect_X 2440 0x0020 Reflect_Y 2441└─── 2442 Used to encode both sets of possible rotations and individual 2443 selected rotations. 2444 2445┌─── 2446 RRSELECTMASK 2447 0x0001 ScreenChangeNotifyMask 2448 0x0002 CrtcChangeNotifyMask Added in version 1.2 2449 0x0004 OutputChangeNotifyMask Added in version 1.2 2450 0x0008 OutputPropertyNotifyMask Added in version 1.2 2451 0x0010 ProviderChangeNotifyMask Added in version 1.4 2452 0x0020 ProviderPropertyNotifyMask Added in version 1.4 2453 0x0040 ResourceChangeNotifyMask Added in version 1.4 2454 0x0080 LeaseNotifyMask Added in version 1.6 2455 2456└─── 2457 Event select mask for RRSelectInput 2458 2459┌─── 2460 RRCONFIGSTATUS 2461 0x0 Success 2462 0x1 InvalidConfigTime 2463 0x2 InvalidTime 2464 0x3 Failed 2465└─── 2466 Return status for requests which depend on time. 2467 2468┌─── 2469 MODEINFO (32) Added in version 1.2 2470 4 CARD32 id 2471 2 CARD16 width in pixels 2472 2 CARD16 height in pixels 2473 4 CARD32 dot clock 2474 2 CARD16 h sync start 2475 2 CARD16 h sync end 2476 2 CARD16 h total 2477 2 CARD16 h skew 2478 2 CARD16 v sync start 2479 2 CARD16 v sync end 2480 2 CARD16 v total 2481 2 CARD16 name length 2482 4 SETofMODEFLAG mode flags 2483└─── 2484 2485 An output mode specifies the complete CRTC timings for 2486 a specific mode. The vertical and horizontal synchronization rates 2487 can be computed given the dot clock and the h total/v total 2488 values. If the dot clock is zero, then all of the timing 2489 parameters and flags are not used, and must be zero as this 2490 indicates that the timings are unknown or otherwise unused. 2491 The name itself will be encoded separately in each usage. 2492 2493┌─── 2494 MODEFLAG 2495 0x00000001 HSyncPositive 2496 0x00000002 HSyncNegative 2497 0x00000004 VSyncPositive 2498 0x00000008 VSyncNegative 2499 0x00000010 Interlace 2500 0x00000020 DoubleScan 2501 0x00000040 CSync 2502 0x00000080 CSyncPositive 2503 0x00000100 CSyncNegative 2504 0x00000200 HSkewPresent 2505 0x00000400 BCast 2506 0x00000800 PixelMultiplex 2507 0x00001000 DoubleClock 2508 0x00002000 ClockDivideBy2 2509└─── 2510┌─── 2511 CONNECTION 2512 0 Connected 2513 1 Disconnected 2514 2 UnknownConnection 2515└─── 2516 2517┌─── 2518 PROVIDER_CAPS Added in version 1.4 2519 0x00000001 SourceOutput 2520 0x00000002 SinkOutput 2521 0x00000004 SourceOffload 2522 0x00000008 SinkOffload 2523└─── 2524 2525A.1.1 Common Types added in version 1.5 of the protocol 2526 2527┌─── 2528 MONITORINFO (16 + 4*n) 2529 4 ATOM name 2530 1 BOOL primary 2531 1 BOOL automatic 2532 2 CARD16 noutputs 2533 2 INT16 x 2534 2 INT16 y 2535 2 CARD16 width in pixels 2536 2 CARD16 height in pixels 2537 4 CARD32 width in millimeters 2538 4 CARD32 height in millimeters 2539 4*n OUTPUT outputs 2540└─── 2541 2542A.2 Protocol Requests 2543 2544Opcodes 1 and 3 were used in the 0.0 protocols, and will return 2545errors if used in version 1.0. 2546 2547┌─── 2548 RRQueryVersion 2549 2550 1 CARD8 major opcode 2551 1 0 RandR opcode 2552 2 3 length 2553 4 CARD32 major version 2554 4 CARD32 minor version 2555 ▶ 2556 1 1 Reply 2557 1 unused 2558 2 CARD16 sequence number 2559 4 0 reply length 2560 1 CARD32 major version 2561 1 CARD32 minor version 2562└─── 2563┌─── 2564 RRSetScreenConfig 2565 2566 1 CARD8 major opcode 2567 1 2 RandR opcode 2568 2 6 length 2569 4 WINDOW window on screen to be configured 2570 4 TIMESTAMP timestamp 2571 4 TIMESTAMP config timestamp 2572 2 SIZEID size index 2573 2 ROTATION rotation/reflection 2574 2 CARD16 refresh rate (1.1 only) 2575 2 CARD16 pad 2576 ▶ 2577 1 1 Reply 2578 1 RRCONFIGSTATUS status 2579 2 CARD16 sequence number 2580 4 0 reply length 2581 4 TIMESTAMP new timestamp 2582 4 TIMESTAMP new configuration timestamp 2583 4 WINDOW root 2584 2 SUBPIXELORDER subpixel order defined in Render 2585 2 CARD16 pad4 2586 4 CARD32 pad5 2587 4 CARD32 pad6 2588└─── 2589┌─── 2590 RRSelectInput 2591 2592 1 CARD8 major opcode 2593 1 4 RandR opcode 2594 2 3 length 2595 4 WINDOW window 2596 2 SETofRRSELECTMASK enable 2597 2 CARD16 pad 2598└─── 2599┌─── 2600 RRGetScreenInfo 2601 2602 1 CARD8 major opcode 2603 1 5 RandR opcode 2604 2 2 length 2605 4 WINDOW window 2606 ▶ 2607 1 1 Reply 2608 1 CARD8 set of Rotations 2609 2 CARD16 sequence number 2610 4 0 reply length 2611 4 WINDOW root window 2612 4 TIMESTAMP timestamp 2613 4 TIMESTAMP config timestamp 2614 2 CARD16 number of SCREENSIZE following 2615 2 SIZEID current size index 2616 2 ROTATION current rotation and reflection 2617 2 CARD16 current rate (added in version 1.1) 2618 2 CARD16 length of rate info (number of CARD16s) 2619 2 CARD16 pad 2620 2621 SCREENSIZE 2622 2 CARD16 width in pixels 2623 2 CARD16 height in pixels 2624 2 CARD16 width in millimeters 2625 2 CARD16 height in millimeters 2626 2627 REFRESH 2628 2 CARD16 number of rates (n) 2629 2n CARD16 rates 2630└─── 2631 2632A.2.1 Protocol Requests added with version 1.2 2633 2634┌─── 2635 RRGetScreenSizeRange 2636 1 CARD8 major opcode 2637 1 6 RandR opcode 2638 2 2 length 2639 4 WINDOW window 2640 ▶ 2641 1 1 Reply 2642 1 unused 2643 2 CARD16 sequence number 2644 4 0 reply length 2645 2 CARD16 minWidth 2646 2 CARD16 minHeight 2647 2 CARD16 maxWidth 2648 2 CARD16 maxHeight 2649 16 unused 2650└─── 2651┌─── 2652 RRSetScreenSize 2653 1 CARD8 major opcode 2654 1 7 RandR opcode 2655 2 5 length 2656 4 WINDOW window 2657 2 CARD16 width 2658 2 CARD16 height 2659 4 CARD32 width in millimeters 2660 4 CARD32 height in millimeters 2661└─── 2662┌─── 2663 RRGetScreenResources 2664 1 CARD8 major opcode 2665 1 8 RandR opcode 2666 2 2 length 2667 4 WINDOW window 2668 ▶ 2669 1 1 Reply 2670 1 unused 2671 2 CARD16 sequence number 2672 4 c+o+8m+(b+p)/4 reply length 2673 4 TIMESTAMP timestamp 2674 4 TIMESTAMP config-timestamp 2675 2 c number of CRTCs 2676 2 o number of outputs 2677 2 m number of modeinfos 2678 2 b total bytes in mode names 2679 8 unused 2680 4c LISTofCRTC crtcs 2681 4o LISTofOUTPUT outputs 2682 32m LISTofMODEINFO modeinfos 2683 b STRING8 mode names 2684 p unused, p=pad(b) 2685└─── 2686┌─── 2687 RRGetOutputInfo 2688 1 CARD8 major opcode 2689 1 9 RandR opcode 2690 2 3 length 2691 4 OUTPUT output 2692 4 TIMESTAMP config-timestamp 2693 ▶ 2694 1 1 Reply 2695 1 RRCONFIGSTATUS status 2696 2 CARD16 sequence number 2697 4 1+c+m+(n+p)/4 reply length 2698 4 TIMESTAMP timestamp 2699 4 CRTC current connected crtc 2700 4 CARD32 width in millimeters 2701 4 CARD32 height in millimeters 2702 1 CONNECTION connection 2703 1 SUBPIXELORDER subpixel-order 2704 2 c number of CRTCs 2705 2 m number of modes 2706 2 p number of preferred modes 2707 2 o number of clones 2708 2 n length of name 2709 4c LISTofCRTC crtcs 2710 4m LISTofMODE modes 2711 4o LISTofOUTPUT clones 2712 n STRING8 name 2713 p unused, p=pad(n) 2714└─── 2715┌─── 2716 RRListOutputProperties 2717 1 CARD8 major opcode 2718 1 10 RandR opcode 2719 2 2 length 2720 4 OUTPUT output 2721 ▶ 2722 1 1 Reply 2723 1 unused 2724 2 CARD16 sequence number 2725 4 n reply length 2726 2 n number of ATOMs in atoms 2727 22 unused 2728 4n LISTofATOM atoms 2729└─── 2730┌─── 2731 RRQueryOutputProperty 2732 1 CARD8 major opcode 2733 1 11 RandR opcode 2734 2 3 request length 2735 4 OUTPUT output 2736 4 ATOM property 2737 ▶ 2738 1 1 Reply 2739 1 unused 2740 2 CARD16 sequence number 2741 4 n reply length 2742 1 BOOL pending 2743 1 BOOL range 2744 1 BOOL immutable 2745 21 unused 2746 4n LISTofINT32 valid values 2747└─── 2748┌─── 2749 RRConfigureOutputProperty 2750 1 CARD8 major opcode 2751 1 12 RandR opcode 2752 2 4+n request length 2753 4 OUTPUT output 2754 4 ATOM property 2755 1 BOOL pending 2756 1 BOOL range 2757 2 unused 2758 4n LISTofINT32 valid values 2759└─── 2760┌─── 2761 RRChangeOutputProperty 2762 1 CARD8 major opcode 2763 1 13 RandR opcode 2764 2 6+(n+p)/4 request length 2765 4 OUTPUT output 2766 4 ATOM property 2767 4 ATOM type 2768 1 CARD8 format 2769 1 mode 2770 0 Replace 2771 1 Prepend 2772 2 Append 2773 2 unused 2774 4 CARD32 length of data in format units 2775 (= n for format = 8) 2776 (= n/2 for format = 16) 2777 (= n/4 for format = 32) 2778 n LISTofBYTE data 2779 (n is a multiple of 2 for format = 16) 2780 (n is a multiple of 4 for format = 32) 2781 p unused, p=pad(n) 2782└─── 2783┌─── 2784 RRDeleteOutputProperty 2785 1 CARD8 major opcode 2786 1 14 RandR opcode 2787 2 3 request length 2788 4 OUTPUT output 2789 4 ATOM property 2790└─── 2791┌─── 2792 RRGetOutputProperty 2793 1 CARD8 major opcode 2794 1 15 RandR opcode 2795 2 7 request length 2796 4 OUTPUT output 2797 4 ATOM property 2798 4 ATOM type 2799 0 AnyPropertyType 2800 4 CARD32 long-offset 2801 4 CARD32 long-length 2802 1 BOOL delete 2803 1 BOOL pending 2804 2 unused 2805 ▶ 2806 1 1 Reply 2807 1 CARD8 format 2808 2 CARD16 sequence number 2809 4 (n+p)/4 reply length 2810 4 ATOM type 2811 0 None 2812 4 CARD32 bytes-after 2813 4 CARD32 length of value in format units 2814 (= 0 for format = 0) 2815 (= n for format = 8) 2816 (= n/2 for format = 16) 2817 (= n/4 for format = 32) 2818 12 unused 2819 n LISTofBYTE value 2820 (n is zero for format = 0) 2821 (n is a multiple of 2 for format = 16) 2822 (n is a multiple of 4 for format = 32) 2823 p unused, p=pad(n) 2824└─── 2825┌─── 2826 RRCreateMode 2827 1 CARD8 major opcode 2828 1 16 RandR opcode 2829 2 10+(n+p)/4 length 2830 4 WINDOW window 2831 32 MODEINFO mode 2832 n STRING8 mode name 2833 p unused, p=pad(n) 2834 ▶ 2835 1 1 Reply 2836 1 unused 2837 2 CARD16 sequence number 2838 4 0 reply length 2839 4 MODE mode 2840 20 unused 2841└─── 2842┌─── 2843 RRDestroyMode 2844 1 CARD8 major opcode 2845 1 17 RandR opcode 2846 2 2 length 2847 4 MODE mode 2848└─── 2849┌─── 2850 RRAddOutputMode 2851 1 CARD8 major opcode 2852 1 18 RandR opcode 2853 2 3 length 2854 4 OUTPUT output 2855 4 MODE mode 2856└─── 2857┌─── 2858 RRDeleteOutputMode 2859 1 CARD8 major opcode 2860 1 19 RandR opcode 2861 2 3 length 2862 4 OUTPUT output 2863 4 MODE mode 2864└─── 2865┌─── 2866 RRGetCrtcInfo 2867 1 CARD8 major opcode 2868 1 20 RandR opcode 2869 2 3 length 2870 4 CRTC crtc 2871 4 TIMESTAMP config-timestamp 2872 ▶ 2873 1 1 Reply 2874 1 RRCONFIGSTATUS status 2875 2 CARD16 sequence number 2876 4 o+p reply length 2877 4 TIMESTAMP timestamp 2878 2 INT16 x 2879 2 INT16 y 2880 2 CARD16 width 2881 2 CARD16 height 2882 4 MODE mode 2883 2 ROTATION current rotation and reflection 2884 2 ROTATION set of possible rotations 2885 2 o number of outputs 2886 2 p number of possible outputs 2887 4o LISTofOUTPUT outputs 2888 4p LISTofOUTPUT possible outputs 2889└─── 2890┌─── 2891 RRSetCrtcConfig 2892 1 CARD8 major opcode 2893 1 21 RandR opcode 2894 2 7+n length 2895 4 CRTC crtc 2896 4 TIMESTAMP timestamp 2897 4 TIMESTAMP config timestamp 2898 2 INT16 x 2899 2 INT16 y 2900 4 MODE mode 2901 2 ROTATION rotation/reflection 2902 2 unused 2903 4n LISTofOUTPUT outputs 2904 ▶ 2905 1 1 Reply 2906 1 RRCONFIGSTATUS status 2907 2 CARD16 sequence number 2908 4 0 reply length 2909 4 TIMESTAMP new timestamp 2910 20 unused 2911└─── 2912┌─── 2913 RRGetCrtcGammaSize 2914 1 CARD8 major opcode 2915 1 22 RandR opcode 2916 2 2 length 2917 4 CRTC crtc 2918 ▶ 2919 1 1 Reply 2920 1 unused 2921 2 CARD16 sequence number 2922 4 0 reply length 2923 2 CARD16 size 2924 22 unused 2925└─── 2926┌─── 2927 RRGetCrtcGamma 2928 1 CARD8 major opcode 2929 1 23 RandR opcode 2930 2 2 length 2931 4 CRTC crtc 2932 ▶ 2933 1 1 Reply 2934 1 unused 2935 2 CARD16 sequence number 2936 4 (6n+p)/4 reply length 2937 2 n size 2938 20 unused 2939 2n LISTofCARD16 red 2940 2n LISTofCARD16 green 2941 2n LISTofCARD16 blue 2942 p unused, p=pad(6n) 2943└─── 2944┌─── 2945 RRSetCrtcGamma 2946 1 CARD8 major opcode 2947 1 24 RandR opcode 2948 2 3+(6n+p)/4 length 2949 4 CRTC crtc 2950 2 n size 2951 2 unused 2952 2n LISTofCARD16 red 2953 2n LISTofCARD16 green 2954 2n LISTofCARD16 blue 2955 p unused, p=pad(6n) 2956└─── 2957 2958A.2.2 Protocol Requests added with version 1.3 2959 2960┌─── 2961 RRGetScreenResourcesCurrent 2962 1 CARD8 major opcode 2963 1 25 RandR opcode 2964 2 2 length 2965 4 WINDOW window 2966 ▶ 2967 1 1 Reply 2968 1 unused 2969 2 CARD16 sequence number 2970 4 c+o+8m+(b+p)/4 reply length 2971 4 TIMESTAMP timestamp 2972 4 TIMESTAMP config-timestamp 2973 2 c number of CRTCs 2974 2 o number of outputs 2975 2 m number of modeinfos 2976 2 b total bytes in mode names 2977 8 unused 2978 4c LISTofCRTC crtcs 2979 4o LISTofOUTPUT outputs 2980 32m LISTofMODEINFO modeinfos 2981 b STRING8 mode names 2982 p unused, p=pad(b) 2983└─── 2984 2985┌─── 2986 RRSetCrtcTransform 2987 1 CARD8 major opcode 2988 1 26 RandR opcode 2989 2 12+(n+p)/4+v length 2990 4 CRTC crtc 2991 36 TRANSFORM transform 2992 2 CARD16 filter length 2993 2 unused 2994 n STRING8 filter name 2995 p unused, p=pad(n) 2996 4v FIXED filter params 2997└─── 2998 2999┌─── 3000 RRGetCrtcTransform 3001 1 CARD8 major opcode 3002 1 27 RandR opcode 3003 2 2 length 3004 4 CRTC crtc 3005 ▶ 3006 1 1 Reply 3007 1 unused 3008 2 CARD16 sequence number 3009 4 16+(pn+pnp)/4+(cn+cnp)/4+pf+cf reply length 3010 36 TRANSFORM pending transform 3011 1 BOOL has transforms 3012 3 unused 3013 36 TRANSFORM current transform 3014 4 unused 3015 2 pn pending filter name length 3016 2 pf pending filter num params 3017 2 cn current filter name length 3018 2 cf current filter num params 3019 pn STRING8 pending filter name 3020 pnp unused, pnp=pad(pn) 3021 4*pf FIXED pending filter params 3022 cn STRING8 current filter name 3023 cnp unused, cnp=pad(cn) 3024 4*cf FIXED current filter params 3025└─── 3026 3027┌─── 3028 RRGetPanning 3029 1 CARD8 major opcode 3030 1 28 RandR opcode 3031 2 2 length 3032 4 CRTC crtc 3033 ▶ 3034 1 1 Reply 3035 1 RRCONFIGSTATUS status 3036 2 CARD16 sequence number 3037 4 1 reply length 3038 4 TIMESTAMP timestamp 3039 2 CARD16 left 3040 2 CARD16 top 3041 2 CARD16 width 3042 2 CARD16 height 3043 2 CARD16 track_left 3044 2 CARD16 track_top 3045 2 CARD16 track_width 3046 2 CARD16 track_height 3047 2 INT16 border_left 3048 2 INT16 border_top 3049 2 INT16 border_right 3050 2 INT16 border_bottom 3051└─── 3052┌─── 3053 RRSetPanning 3054 1 CARD8 major opcode 3055 1 29 RandR opcode 3056 2 9 length 3057 4 CRTC crtc 3058 4 TIMESTAMP timestamp 3059 2 CARD16 left 3060 2 CARD16 top 3061 2 CARD16 width 3062 2 CARD16 height 3063 2 CARD16 track_left 3064 2 CARD16 track_top 3065 2 CARD16 track_width 3066 2 CARD16 track_height 3067 2 INT16 border_left 3068 2 INT16 border_top 3069 2 INT16 border_right 3070 2 INT16 border_bottom 3071 ▶ 3072 1 1 Reply 3073 1 RRCONFIGSTATUS status 3074 2 CARD16 sequence number 3075 4 0 reply length 3076 4 TIMESTAMP new timestamp 3077 20 unused 3078└─── 3079 3080┌─── 3081 RRSetOutputPrimary 3082 1 CARD8 major opcode 3083 1 30 RandR opcode 3084 2 3 length 3085 4 WINDOW window 3086 4 OUTPUT output 3087└─── 3088 3089┌─── 3090 RRGetOutputPrimary 3091 1 CARD8 major opcode 3092 1 31 RandR opcode 3093 2 2 length 3094 4 WINDOW window 3095 ▶ 3096 1 1 Reply 3097 1 unused 3098 2 CARD16 sequence number 3099 4 CARD32 length 3100 4 OUTPUT output 3101 4 CARD32 pad1 3102 4 CARD32 pad2 3103 4 CARD32 pad3 3104 4 CARD32 pad4 3105└─── 3106 3107A.2.3 Protocol Requests added with version 1.4 3108 3109┌─── 3110 RRGetProviders 3111 1 CARD8 major opcode 3112 1 32 RandR opcode 3113 2 2 length 3114 4 WINDOW window 3115 ▶ 3116 1 1 Reply 3117 1 unused 3118 2 CARD16 sequence number 3119 4 p length 3120 4 TIMESTAMP timestamp 3121 2 p number of Providers 3122 18 unused 3123 4p LISTofPROVIDERS providers 3124└─── 3125┌─── 3126 RRGetProviderInfo 3127 1 CARD8 major opcode 3128 1 33 RandR opcode 3129 2 3 length 3130 4 PROVIDER provider 3131 4 TIMESTAMP config-timestamp 3132 ▶ 3133 1 1 Reply 3134 1 RRCONFIGSTATUS status 3135 2 CARD16 sequence number 3136 4 1+c+o+(a*2)+(n+p)/4 reply length 3137 4 TIMESTAMP timestamp 3138 4 CARD32 capabilities 3139 2 c number of crtcs 3140 2 o number of outputs 3141 2 a number of associated providers 3142 2 n length of name 3143 8 unused 3144 4c LISTofCRTC crtcs 3145 4o LISTofOUTPUT outputs 3146 4a LISTofPROVIDER associated providers 3147 4a CARD32 associated provider capability 3148 n STRING8 name 3149 p unused, p=pad(n) 3150└─── 3151┌─── 3152 RRSetProviderOffloadSink 3153 1 CARD8 major opcode 3154 1 34 RandR opcode 3155 2 4 length 3156 4 PROVIDER provider 3157 4 PROVIDER offload sink provider 3158 4 TIMESTAMP timestamp 3159└─── 3160┌─── 3161 RRSetProviderOutputSource 3162 1 CARD8 major opcode 3163 1 35 RandR opcode 3164 2 4 length 3165 4 PROVIDER provider 3166 4 PROVIDER output source provider 3167 4 TIMESTAMP timestamp 3168└─── 3169┌─── 3170 RRListProviderProperties 3171 1 CARD8 major opcode 3172 1 36 RandR opcode 3173 2 2 length 3174 4 PROVIDER provider 3175 ▶ 3176 1 1 Reply 3177 1 unused 3178 2 CARD16 sequence number 3179 4 n reply length 3180 2 n number of ATOMs in atoms 3181 22 unused 3182 4n LISTofATOM atoms 3183└─── 3184┌─── 3185 RRQueryProviderProperty 3186 1 CARD8 major opcode 3187 1 37 RandR opcode 3188 2 3 request length 3189 4 PROVIDER provider 3190 4 ATOM property 3191 ▶ 3192 1 1 Reply 3193 1 unused 3194 2 CARD16 sequence number 3195 4 n reply length 3196 1 BOOL pending 3197 1 BOOL range 3198 1 BOOL immutable 3199 21 unused 3200 4n LISTofINT32 valid values 3201└─── 3202┌─── 3203 RRConfigureProviderProperty 3204 1 CARD8 major opcode 3205 1 38 RandR opcode 3206 2 4+n request length 3207 4 PROVIDER provider 3208 4 ATOM property 3209 1 BOOL pending 3210 1 BOOL range 3211 2 unused 3212 4n LISTofINT32 valid values 3213└─── 3214┌─── 3215 RRChangeProviderProperty 3216 1 CARD8 major opcode 3217 1 39 RandR opcode 3218 2 6+(n+p)/4 request length 3219 4 PROVIDER provider 3220 4 ATOM property 3221 4 ATOM type 3222 1 CARD8 format 3223 1 mode 3224 0 Replace 3225 1 Prepend 3226 2 Append 3227 2 unused 3228 4 CARD32 length of data in format units 3229 (= n for format = 8) 3230 (= n/2 for format = 16) 3231 (= n/4 for format = 32) 3232 n LISTofBYTE data 3233 (n is a multiple of 2 for format = 16) 3234 (n is a multiple of 4 for format = 32) 3235 p unused, p=pad(n) 3236└─── 3237┌─── 3238 RRDeleteProviderProperty 3239 1 CARD8 major opcode 3240 1 40 RandR opcode 3241 2 3 request length 3242 4 PROVIDER provider 3243 4 ATOM property 3244└─── 3245┌─── 3246 RRGetProviderProperty 3247 1 CARD8 major opcode 3248 1 41 RandR opcode 3249 2 7 request length 3250 4 PROVIDER provider 3251 4 ATOM property 3252 4 ATOM type 3253 0 AnyPropertyType 3254 4 CARD32 long-offset 3255 4 CARD32 long-length 3256 1 BOOL delete 3257 1 BOOL pending 3258 2 unused 3259 ▶ 3260 1 1 Reply 3261 1 CARD8 format 3262 2 CARD16 sequence number 3263 4 (n+p)/4 reply length 3264 4 ATOM type 3265 0 None 3266 4 CARD32 bytes-after 3267 4 CARD32 length of value in format units 3268 (= 0 for format = 0) 3269 (= n for format = 8) 3270 (= n/2 for format = 16) 3271 (= n/4 for format = 32) 3272 12 unused 3273 n LISTofBYTE value 3274 (n is zero for format = 0) 3275 (n is a multiple of 2 for format = 16) 3276 (n is a multiple of 4 for format = 32) 3277 p unused, p=pad(n) 3278└─── 3279 3280A.2.4 Protocol Requests added with version 1.5 3281 3282┌─── 3283 RRGetMonitors 3284 1 CARD8 major opcode 3285 1 42 RandR opcode 3286 2 2 request length 3287 4 WINDOW window 3288 ▶ 3289 1 1 Reply 3290 1 unused 3291 2 CARD16 sequence number 3292 4 6*n + o reply length 3293 4 TIMESTAMP timestamp 3294 4 n nmonitors 3295 4 o noutputs 3296 12 unused 3297 n*24+o*4 LISTofMONITORINFO monitors 3298└─── 3299┌─── 3300 RRSetMonitor 3301 1 CARD8 major opcode 3302 1 43 RandR opcode 3303 2 6 + o request length 3304 4 WINDOW window 3305 24+o MONITORINFO monitorinfo 3306└─── 3307┌─── 3308 RRDeleteMonitor 3309 1 CARD8 major opcode 3310 1 44 RandR opcode 3311 2 3 request length 3312 4 WINDOW window 3313 4 ATOM name 3314└─── 3315 3316A.3 Protocol Events 3317 3318┌─── 3319 RRScreenChangeNotify 3320 1 Base + 0 code 3321 1 ROTATION new rotation and reflection 3322 2 CARD16 sequence number 3323 4 TIMESTAMP timestamp 3324 4 TIMESTAMP configuration timestamp 3325 4 WINDOW root window 3326 4 WINDOW request window 3327 2 SIZEID size ID 3328 2 SUBPIXELORDER subpixel order defined in Render 3329 2 CARD16 width in pixels 3330 2 CARD16 height in pixels 3331 2 CARD16 width in millimeters 3332 2 CARD16 height in millimeters 3333└─── 3334 3335A.3.1 Protocol Events added with version 1.2 3336 3337┌─── 3338 RRCrtcChangeNotify 3339 1 Base + 1 code 3340 1 0 sub-code 3341 2 CARD16 sequence number 3342 4 TIMESTAMP timestamp 3343 4 WINDOW request window 3344 4 CRTC crtc affected 3345 4 MODE mode in use 3346 2 ROTATION new rotation and reflection 3347 2 unused 3348 2 INT16 x 3349 2 INT16 y 3350 2 CARD16 width 3351 2 CARD16 height 3352└─── 3353┌─── 3354 RROutputChangeNotify 3355 1 Base + 1 code 3356 1 1 sub-code 3357 2 CARD16 sequence number 3358 4 TIMESTAMP timestamp 3359 4 TIMESTAMP configuration timestamp 3360 4 WINDOW request window 3361 4 OUTPUT output affected 3362 4 CRTC crtc in use 3363 4 MODE mode in use 3364 2 ROTATION rotation in use 3365 1 CONNECTION connection status 3366 1 SUBPIXELORDER subpixel order 3367└─── 3368┌─── 3369 RROutputPropertyNotify 3370 1 Base + 1 code 3371 1 2 sub-code 3372 2 CARD16 sequence number 3373 4 WINDOW window 3374 4 OUTPUT output 3375 4 ATOM atom 3376 4 TIMESTAMP time 3377 1 state 3378 0 NewValue 3379 1 Deleted 3380 11 unused 3381└─── 3382 3383A.3.2 Protocol Events added with version 1.4 3384┌─── 3385 RRProviderChangeNotify 3386 1 Base + 1 code 3387 1 3 sub-code 3388 2 CARD16 sequence number 3389 4 TIMESTAMP timestamp 3390 4 WINDOW request window 3391 4 PROVIDER provider affected 3392 16 unused 3393└─── 3394┌─── 3395 RRProviderPropertyNotify 3396 1 Base + 1 code 3397 1 4 sub-code 3398 2 CARD16 sequence number 3399 4 WINDOW window 3400 4 PROVIDER provider 3401 4 ATOM atom 3402 4 TIMESTAMP time 3403 1 state 3404 0 NewValue 3405 1 Deleted 3406 11 unused 3407└─── 3408┌─── 3409 RRResourceChangeNotify 3410 1 Base + 1 code 3411 1 5 sub-code 3412 2 CARD16 sequence number 3413 4 TIMESTAMP time 3414 4 WINDOW window 3415 20 unused 3416└─── 3417A.4 Protocol Errors 3418 3419┌─── 3420 ERRORS 3421 Base + 0 Output 3422 Base + 1 Crtc 3423 Base + 2 Mode 3424 Base + 3 Provider 3425└─── 3426 3427Bibliography 3428 3429[RANDR] Gettys, Jim and Keith Packard, "The X Resize and Rotate 3430 Extension - RandR", Proceedings of the 2001 USENIX Annual 3431 Technical Conference, Boston, MA 3432 3433[RENDER] 3434 Packard, Keith, "The X Rendering Extension", work in progress, 3435 https://gitlab.freedesktop.org/xorg/proto/xorgproto/raw/master/renderproto.txt 3436