randrproto.txt revision 17ca54c3
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 For each output in 'info.outputs, each one is removed from all 1697 pre-existing Monitors. If removing the output causes the list of 1698 outputs for that Monitor to become empty, then that Monitor will 1699 be deleted as if RRDeleteMonitor were called. 1700 1701 Only one monitor per screen may be primary. If 'info.primary' 1702 is true, then the primary value will be set to false on all 1703 other monitors on the screen. 1704 1705 RRSetMonitor generates a ConfigureNotify event on the root 1706 window of the screen. 1707 1708┌─── 1709 RRDeleteMonitor 1710 window : WINDOW 1711 name: ATOM 1712└─── 1713 Errors: Window, Atom, Value 1714 1715 Deletes the named Monitor. 1716 1717 'name' must be a valid atom or an Atom error results. 1718 1719 'name' must match the name of a Monitor on the screen, or a 1720 Value error results. 1721 1722 RRDeleteMonitor generates a ConfigureNotify event on the root 1723 window of the screen. 1724 1725 ❧❧❧❧❧❧❧❧❧❧❧ 1726 17277.6. Extension Requests added in version 1.6 of the extension. 1728 1729┌─── 1730 RRCreateLease 1731 window : WINDOW 1732 lid: LEASE 1733 crtcs: LISTofCRTC 1734 outputs: LISTofOUTPUT 1735 ▶ 1736 nfd: CARD8 1737 lease: FD 1738└─── 1739 Errors: IdChoice, Window, Access, Value, CRTC, Output 1740 1741 Creates a new Lease called 'lid' for the specified crtcs and 1742 outputs from the screen defined by 'window'. Returns a KMS/DRM 1743 file descriptor which can control the leased objects directly 1744 through the kernel. While leased, all resources will appear to 1745 be 'useless' to clients other than the leasing client as 1746 follows: 1747 1748 • Crtcs are reported as having no 'possible-outputs' and all 1749 other values reported as if the crtc were disabled. 1750 1751 • Outputs are reported as having no crtcs they can be 1752 connected to, no clones they can share a crtc with, will 1753 report a connection status of Disconnected, and will show 1754 the current crtc as if it were disabled. 1755 1756 The lease remains in effect until the file descriptor is 1757 closed, even if the client holding the lease disconnects from 1758 the X server. 1759 1760 Returns an Access error if any of the named resources are 1761 already leased to another client. 1762 1763┌─── 1764 RRFreeLease 1765 lid: LEASE 1766 terminate: BOOL 1767└─── 1768 Errors: Lease 1769 1770 Frees the reference to the lease 'lid'. If 'terminate' is 1771 true, then the lease is terminated and all leased resources 1772 returned to the X server. If 'terminate' is false, then the 1773 lease remains in effect, but the X server no longer has a name 1774 for it. 1775 1776 ❧❧❧❧❧❧❧❧❧❧❧ 17778. Extension Events 1778 1779Clients MAY select for ConfigureNotify on the root window to be 1780informed of screen changes. This may be advantageous if all your 1781client needs to know is the size of the root window, as it avoids 1782round trips to set up the extension. 1783 1784RRScreenChangeNotify is sent if RRSelectInput has requested it 1785whenever properties of the screen change, which may be due to external 1786factors, such as re-cabling a monitor, etc. 1787 1788┌─── 1789 RRScreenChangeNotify 1790 1791 rotation: ROTATION; new rotation 1792 sequenceNumber: CARD16 low 16 bits of request seq. number 1793 timestamp: TIMESTAMP time screen was changed 1794 configTimestamp: TIMESTAMP time config data was changed 1795 root: WINDOW root window of screen 1796 window: WINDOW window requesting notification 1797 size-id: SIZEID index of new SCREENSIZE 1798 subpixelOrder: SUBPIXELORDER order of subpixels 1799 widthInPixels: CARD16 width in pixels of the new SCREENSIZE 1800 heightInPixels: CARD16 height in pixels of the new SCREENSIZE 1801 widthInMillimeters: CARD16 width in mm of the new SCREENSIZE 1802 heightInMillimeters: CARD16 height in mm of the new SCREENSIZE 1803└─── 1804 This event is generated whenever the screen configuration is changed 1805 and sent to requesting clients. 'timestamp' indicates when the 1806 screen configuration was changed. 'configTimestamp' says when the 1807 last time the configuration was changed. 'root' is the root of the 1808 screen the change occurred on, 'window' is window selecting for this 1809 event. 'size-id' contains the index of the current size. 1810 1811 This event is sent whenever the screen's configuration changes 1812 or if a new screen configuration becomes available that was 1813 not available in the past. In this case (config-timestamp in 1814 the event not being equal to the config-timestamp returned in 1815 the last call to RRGetScreenInfo), the client MUST call 1816 RRGetScreenInfo to update its view of possible screen 1817 configurations to have a correct view of possible screen 1818 organizations. 1819 1820 Clients which select screen change notification events may be 1821 sent an event immediately if the screen configuration was 1822 changed between when they connected to the X server and 1823 selected for notification. This is to prevent a common race 1824 that might occur on log-in, where many applications start up 1825 just at the time when a display manager or log in script might 1826 be changing the screen size or configuration. 1827 1828 Note that the sizes in this event reflect the new SCREENSIZE and 1829 thus will appear rotated by the 'rotation' parameter from the sizes 1830 of the screen itself. In other words, when rotation is 90 or 270, 1831 widthInPixels in this event will be the same as the height value 1832 from a ConfigureNotify that reflects the same size change. This 1833 will probably confuse developers. 1834 18358.1 Events added in version 1.2 of the RandR extension 1836 1837┌─── 1838 RROutputChangeNotify: 1839 timestamp: TIMESTAMP time screen was reconfigured 1840 config-timestamp: TIMESTAMP time available config data was changed 1841 window: WINDOW window requesting notification 1842 output: OUTPUT output affected by change 1843 crtc: CRTC connected CRTC or None 1844 mode: MODE mode in use on CRTC or None 1845 connection: CONNECTION connection status 1846└─── 1847 1848 This event is generated whenever the available output configurations 1849 have changed and is sent to requesting clients. 'timestamp' 1850 indicates when the crtc configuration was changed by a client. 1851 'config-timestamp' says when the last time the available 1852 configurations changed. 'root' is the root of the screen the change 1853 occurred on, 'window' is window selecting for this event. The 1854 precise change can be detected by examining the new state of the 1855 system. 1856 1857 Changes in version 1.6 of the protocol: 1858 1859 When a “non-desktop” device is connected, this event will be 1860 delivered when the connection status of the output changes, 1861 however the 'connection' value will be set to 'Disconnected'. 1862 1863┌─── 1864 RROutputPropertyNotify: 1865 window: WINDOW window requesting notification 1866 output: OUTPUT output affected by change 1867 atom: ATOM affected property 1868 time: TIMESTAMP time property was changed 1869 subpixel-order: SUBPIXELORDER order of subpixels 1870 state: { NewValue, Deleted } new property state 1871└─── 1872 1873 This event is reported to clients selecting RROutputPropertyChange 1874 on the window and is generated with state NewValue when a property 1875 of the window is changed using RRChangeOutputProperty even when 1876 adding zero-length data and when replacing all or part of a property 1877 with identical data. It is generated with state Deleted when a 1878 property of the window is deleted using either 1879 RRDeleteOutputProperty or RRGetOutputProperty. The timestamp 1880 indicates the server time when the property was changed. 1881 1882┌─── 1883 RRCrtcChangeNotify 1884 timestamp: TIMESTAMP time monitor was changed 1885 window: WINDOW window requesting notification 1886 crtc: CRTC CRTC which changed 1887 mode: MODE new mode 1888 rotation: ROTATION; new rotation 1889 x: INT16 x position of CRTC within screen 1890 y: INT16 y position of CRTC within screen 1891 width: CARD16 width of new configuration 1892 height: CARD16 height of new configuration 1893└─── 1894 This event is generated whenever the CRTC configuration is changed 1895 and sent to requesting clients. 'timestamp' indicates when the 1896 CRTC configuration was changed. 'window' is window selecting for this 1897 event. 'mode' is the new mode, or None if the crtc is disabled. 1898 'x' and 'y' mark the location in the screen where this CRTC 1899 is reading data. 'width' and 'height' indicate the size of the 1900 CRTC viewport, which is the mode size adjusted by the optional 1901 Border output property described below. 'x', 'y, 'width' and 1902 'height' are all zero when 'mode' is None. 1903 1904 This event is sent whenever the monitor's configuration changes 1905 or if a new monitor configuration becomes available that was 1906 not available in the past. In this case, the client MUST call 1907 RRGetCrtcInfo to update its view of possible monitor 1908 configurations to have a correct view of possible monitor 1909 organizations. 1910 1911 Clients which select monitor change notification events may be 1912 sent an event immediately if the monitor configuration was 1913 changed between when they connected to the X server and 1914 selected for notification. This is to prevent a common race 1915 that might occur on log-in, where many applications start up 1916 just at the time when a display manager or log in script might 1917 be changing the monitor size or configuration. 1918 19198.2 Events added in version 1.4 of the RandR extension 1920 1921┌─── 1922 RRProviderChangeNotify: 1923 timestamp: TIMESTAMP time screen was reconfigured 1924 window: WINDOW window requesting notification 1925 provider: PROVIDER provider affected by change 1926└─── 1927 1928 This event is generated whenever the role for a provider has changed 1929 and is sent to requesting clients. 'timestamp' indicates when the 1930 provider configuration was changed by a client. 'window' is the 1931 window selecting for this event. The precise change can be detected 1932 by examining the new state of the system. 1933 1934┌─── 1935 RRProviderPropertyNotify: 1936 window: WINDOW window requesting notification 1937 provider: PROVIDER provider affected by change 1938 atom: ATOM affected property 1939 time: TIMESTAMP time property was changed 1940 state: { NewValue, Deleted } new property state 1941└─── 1942 1943 This event is reported to clients selecting RRProviderPropertyChange 1944 on the window and is generated with state NewValue when a property 1945 of the window is changed using RRChangeProviderProperty even when 1946 adding zero-length data and when replacing all or part of a property 1947 with identical data. It is generated with state Deleted when a 1948 property of the window is deleted using either 1949 RRDeleteProviderProperty or RRGetProviderProperty. The timestamp 1950 indicates the server time when the property was changed. 1951 1952┌─── 1953 RRResourceChangeNotify: 1954 window: WINDOW window requesting notification 1955 time: TIMESTAMP time property was changed 1956└─── 1957 1958 This event is reported to clients selecting RRResourceChange 1959 on the window and is generated whenever the set of available 1960 RandR resources associated with the screen has changed, either 1961 created or destroyed. Querying the list of available resources 1962 with RRGetScreenResources and RRGetProviders will return the new set. 1963 19648.3 Events added in version 1.6 of the RandR extension 1965 1966┌─── 1967 RRLeaseNotify: 1968 timestamp : TIMESTAMP time screen was reconfigured 1969 window : WINDOW window requesting notification 1970 lease : LEASE lease 1971 created : BOOL created/destroyed indicator 1972└─── 1973 1974 This event is generated whenever a lease has been created or 1975 destroyed and is sent to requesting clients. 'timestamp' 1976 indicates when the change happend. 'window' is the window 1977 selecting for this event. 1978 1979 ❧❧❧❧❧❧❧❧❧❧❧ 1980 19819. Properties 1982 1983Properties are used for output specific parameters, and for announcing 1984static or rarely changing data. Announced data is typically 1985immutable. Properties are also used for evaluating new parameters 1986before adding them to the RandR protocol. 1987 1988The following properties are hereby declared official, and drivers SHOULD 1989prefix driver specific properties with '_', unless they are planned to be 1990added to this specification. List values, that are not declared by the table 1991below, and will remain driver specific or are not planned to be added to this 1992specification, SHOULD be prefixed with "_" as well in order to avoid name 1993space or semantics clashes with future extensions of these values. 1994 1995Beginning with version 1.3 of the RandR extension, certain properties 1996are mandatory and MUST be provided by implementations. Earlier 1997versions of the RandR extension MAY provide these properties as well, 1998as long as the semantics are not altered. Clients SHOULD fall back 1999gracefully to lower version functionality, though, if the driver 2000doesn't handle a mandatory property correctly. 2001 2002Changes in version 1.6 of the protocol: 2003 2004When a “non-desktop” device is connected, the property information 2005will be correct for the device, even though RRGetOutputInfo 2006reports the device as disconnected. The “non-desktop” property will be 2007set to 1 for such devices and not present on other devices. 2008 20099.1 Known properties 2010 2011 "Backlight" aka RR_PROPERTY_BACKLIGHT 2012 Type: INTEGER 2013 Format: 32 2014 Num. items: 1 2015 Flags: - 2016 Range/List: 0-x (driver specific) 2017 2018 This property controls the brightness on laptop panels and equivalent 2019 displays with a backlight controller. The driver specific maximum 2020 value MUST turn the backlight to full brightness, 1 SHOULD turn the 2021 backlight to minimum brightness, 0 SHOULD turn the backlight off. 2022 2023 "CloneList" aka RR_PROPERTY_CLONE_LIST 2024 Type: ATOM 2025 Format: 32 2026 Num. items: 2*n 2027 Flags: Immutable 2028 Range/List: 0- 2029 2030 Some combinations of outputs on some cards cannot be served 2031 independently from each other, because they are wired up to the same 2032 encoder outputs. 2033 This property lists all output + signal format pairs that are 2034 driven together with this output, and thus can only be programmed in 2035 clone mode with the same CRTC. 2036 This property MUST be symmetric, but may change with changing signal 2037 format. I.e. if the property for DVI-1/VGA specifies VGA-1/VGA to be 2038 cloned, VGA-1/VGA has to list DVI-1/VGA as well. 2039 Outputs / format pairs listed in this property MUST be included in the 2040 CompatibilityList. 2041 2042 "CompatibilityList" aka RR_PROPERTY_COMPATIBILITY_LIST 2043 Type: ATOM 2044 Format: 32 2045 Num items: 2*n 2046 Flags: Immutable 2047 Range/List: 0- 2048 2049 Some combinations of outputs on some cards cannot be served at all, 2050 because the according encoder is only capable of driving one output at 2051 a time. 2052 This property lists all output + signal format pairs that can be 2053 driven together with this output. NULL atoms specify any output / any 2054 signal format, respectively. 2055 This property MUST be symmetric, but may change with changing signal 2056 format. I.e. if the property for DVI-1/TMDS specifies VGA-1/VGA to be 2057 available, VGA-1/VGA has to list DVI-1/TMDS as well. 2058 2059 "ConnectorNumber" aka RR_PROPERTY_CONNECTOR_NUMBER 2060 Type: INTEGER 2061 Format: 32 2062 Num items: 1 2063 Flags: Immutable, Static 2064 Range/List: 0- 2065 2066 Outputs that route their signal to the same connector MUST 2067 have the same connector number. Outputs with the same 2068 connector number MUST route their signal to the same 2069 connector, except if it is 0, which indicates unknown 2070 connectivity. 1 is called the primary connector, 2 the 2071 secondary. 3 is typically a TV connector, but that is completely 2072 driver / hardware dependent. 2073 Outputs with the same connector number SHOULD have the same 2074 connector type. Meaning and client behavior for mismatching 2075 connector types is undefined at the moment. 2076 2077 "ConnectorType" aka RR_PROPERTY_CONNECTOR_TYPE 2078 Type: ATOM 2079 Format: 32 2080 Num items: 1 2081 Flags: Immutable, Static 2082 Range/List: unknown VGA DVI DVI‐I DVI‐A DVI‐D HDMI Panel 2083 TV TV-Composite TV-SVideo TV-Component 2084 TV-SCART TV-C4 DisplayPort 2085 2086 Connector type, as far as known to the driver. 2087 Values with dashes (TV‐Composite) describe more specific versions of 2088 the base values (TV). The former SHOULD be used if the connector is 2089 not capable of producing other signal formats. The later SHOULD be 2090 used if the exact connector is unknown, or the connector is a 2091 multi‐format connector that is not described otherwise. DVI, for 2092 instance, SHOULD be handled like a DVI‐I connector, unless additional 2093 information is available to the user agent. PANEL describes 2094 laptop‐internal (normally LVDS) displays. TV, TV‐SCART, TV‐Component, 2095 and TV‐C4 with signal format VGA are valid combinations and describe 2096 RGB TV signals. 2097 2098 "EDID" aka RR_PROPERTY_RANDR_EDID 2099 Type: INTEGER 2100 Format: 8 2101 Num items: n 2102 Flags: Immutable 2103 Range/List: - 2104 2105 Raw EDID data from the device attached to the according 2106 output. Should include main EDID data and all extension 2107 blocks. Previously known as EdidData. 2108 2109 “non-desktop” aka RR_PROPERTY_NON_DESKTOP 2110 Type: INTEGER 2111 Format: 32 2112 Num items: 1 2113 Flags Immutable 2114 Range/List: 0-1 2115 2116 Indicates whether the device attached to this output should not 2117 be considered part of the normal desktop. When set to 0 or not 2118 present, the output should be presented as part of the 2119 desktop. 2120 2121 When set to 1, the output should not be presented as part of 2122 the desktop. To not present an output as part of the desktop, 2123 the normal desktop environment should not be shown on this 2124 output, nor should desktop applications be positioned on it. 2125 2126 When set to 1, RRGetOutputInfo will always report connection status 2127 Disconnected, but RROutputChangeNotify events will still be 2128 delivered when the connection status changes and all other 2129 information about the output and connected device will be 2130 reported correctly. 2131 2132 "SignalFormat" aka RR_PROPERTY_SIGNAL_FORMAT 2133 Type: ATOM 2134 Format: 32 2135 Num items: 1 2136 Flags: - 2137 Range/List: unknown VGA TMDS LVDS Composite Composite-PAL 2138 Composite-NTSC Composite-SECAM SVideo 2139 Component DisplayPort 2140 2141 Signal format / physical protocol format that is used for the 2142 specified output. valid-values lists all possible formats on this 2143 output, which SHOULD be a subset of the list above and MUST be static. 2144 Values with dashes (Composite-PAL) describe more specific versions of 2145 the base values (Composite) and SHOULD be used if known to the driver. 2146 A driver MAY change this property of an output if the underlying 2147 hardware indicates a protocol change (e.g. TV formats). Clients are 2148 allowed to change the signal format in order to select a different 2149 signal format (e.g. Composite etc.) or physical protocol (e.g. VGA or 2150 TMDS on DVI-I). 2151 Laptop panels SHOULD not be detected with this property, but rather by 2152 ConnectorType. 2153 2154 "SignalProperties" aka RR_PROPERTY_SIGNAL_FORMAT 2155 Type: ATOM 2156 Format: 32 2157 Num items: n 2158 Flags: - 2159 Range/List: For Composite signals: 2160 NTSC NTSC-M NTSC-J NTSC-N NTSC-4.43 NTSC-film 2161 PAL PAL-B PAL-G PAL-H PAL-H PAL-I PAL-M PAL-D 2162 PAL-N PAL-Nc PAL-L PAL-60 2163 SECAM SECAM-L SECAM-B SECAM-G SECAM-D SECAM-K 2164 SECAM-H SECAM-K 2165 For TMDS signals: 2166 SingleLink DualLink 2167 For DisplayPort signals: 2168 Lane1 Lane2 Lane4 LowSpeed HiSpeed 2169 2170 Properties of the signal format that is currently used for the 2171 specified output. valid-values lists all possible properties on this 2172 output, which SHOULD be a subset of the list above. It will change if 2173 SignalFormat changes. Multiple properties are allowed. 2174 Values with dashes (PAL-B) describe more specific versions of the base 2175 values (PAL) and SHOULD be used if known to the driver. A driver MAY 2176 change this property of an output if the underlying hardware indicates 2177 a signal change (e.g. TV formats). Clients are allowed to change the 2178 properties in order to select a different signal subformat. 2179 2180 "Border" aka RR_PROPERTY_BORDER 2181 Type: CARDINAL 2182 Format: 16 2183 Num items: 0, 1, 2, or 4 2184 Flags: Immutable 2185 Range/List: 0- 2186 2187 This property is a list of integers specifying adjustments for the edges 2188 of the displayed image. How this property is applied depends on the 2189 number of elements in the list: 2190 2191 0 = No border is applied 2192 1 = A border of Border[0] is applied to all four sides of the image. 2193 2 = A border of Border[0] is applied to the left and right sides of 2194 the image, and a border of Border[1] is applied to the top and 2195 bottom. 2196 4 = The border dimensions are as follows: 2197 Border[0]: left 2198 Border[1]: top 2199 Border[2]: right 2200 Border[3]: bottom 2201 2202 Note that how many configuration dimensions are actually supported is 2203 specified by the BorderDimensions property described below. If more than 2204 BorderDimensions values are specified, the extra values are ignored. 2205 2206 These border dimensions shrink the region of pixels displayed by the 2207 CRTC by the corresponding number of rows or columns, and is applied 2208 after the CRTC transform. For example, a mode with a 1920x1080 active 2209 region, border dimensions of [ 10, 20, 30, 40 ], and a ½x scaling 2210 transform would display a rectangle of 940x510 pixels from the scanout 2211 pixmap scaled to 1880x1020 raster pixels positioned at (10, 20) in 2212 display raster space. 2213 2214 Raster pixels in the border are black. 2215 2216 This property is created with pending == TRUE, so changes are not 2217 applied immediately and instead take effect at the next RRSetCrtcConfig. 2218 2219 If multiple outputs with different border settings are bound to the same 2220 CRTC when the configuration is changed, the behavior is undefined. 2221 2222 If the length of the property is less than four when the CRTC is 2223 configured, the missing values are assumed to be zero. If the length is 2224 greater than four, the extra values are ignored. 2225 2226 If the width of the mode is less than or equal to the sum of the left 2227 and right borders, then the left and right border settings are ignored. 2228 Likewise, if the height of the mode is less than or equal to the sum of 2229 the top and bottom borders, the top and bottom borders are ignored. 2230 2231 "BorderDimensions" aka RR_PROPERTY_BORDER_DIMENSIONS 2232 Type: CARDINAL 2233 Format: 8 2234 Num items: 1 2235 Flags: Immutable, Static 2236 Range/List: 0, 1, 2, or 4 2237 2238 This property lists how many border adjustment parameters can actually 2239 be used: 2240 2241 0 = no borders are supported 2242 1 = a single border value is applied to all four sides of the image 2243 2 = left/right and top/bottom borders can be specified independently 2244 4 = all four borders can be specified independently 2245 2246 "GUID" aka RR_PROPERTY_GUID 2247 Type: INTEGER 2248 Format: 8 2249 Num items: 16 2250 Flags: Immutable 2251 Range/List: - 2252 2253 Some display devices, such as DisplayPort 1.2 devices, have globally 2254 unique identifiers. When such an identifier is available, this property 2255 contains its raw bytes. 2256 2257 "TILE" aka RR_PROPERTY_RANDR_TILE 2258 Type: INTEGER 2259 Format: 32 2260 Num items: 8 2261 Flags: Immutable 2262 Range/List: - 2263 2264 Tile monitors have an array of values describing the tiling, 2265 based on DisplayID v1.3 2266 2267 The 8 elements are: 2268 0: group id - The tile group identifier 2269 1: flags - flags for tile group 2270 0x1 = single monitor enclosure 2271 2: number of horizontal tiles in tile group 2272 3: number of vertical tiles in tile group 2273 4: horizontal tile location for this tile 2274 5: vertical tile location for this tile 2275 6: horizontal tile size for this tile 2276 7: vertical tile size for this tile 2277 22789.2 Properties introduced with version 1.2 of the RandR extension 2279 2280Property Immutable Mandatory since 2281──────── ───────── ─────────────── 2282EDID yes n/a 2283 2284EDID is provided by the RandR frontend, thus not driver specific. 2285 2286 22879.3 Properties introduced with version 1.3 of the RandR extension 2288 2289Property Immutable Mandatory since 2290──────── ───────── ─────────────── 2291CloneList yes not mandatory 2292CompatibilityList yes not mandatory 2293ConnectorNumber yes: static not mandatory 2294ConnectorType yes: static RandR 1.3 2295SignalFormat no RandR 1.3 2296SignalProperties no not mandatory 2297 22989.4 Properties introduced with version 1.3.1 of the RandR extension 2299 2300Property Immutable Mandatory since 2301──────── ───────── ─────────────── 2302Backlight no not mandatory 2303 23049.5 Properties introduced with version 1.4.0 of the RandR extension 2305 2306Property Immutable Mandatory since 2307──────── ───────── ─────────────── 2308Border yes not mandatory 2309BorderDimensions yes: static not mandatory 2310 23119.6 Properties introduced with version 1.4.1 of the RandR extension 2312 2313Property Immutable Mandatory since 2314──────── ───────── ─────────────── 2315GUID yes not mandatory 2316 23179.7 Properties introduced with version 1.5 of the RandR extension 2318 2319Property Immutable Mandatory since 2320──────── ───────── ─────────────── 2321TILE yes not mandatory 2322 23239.8 Properties introduced with version 1.6 of the RandR extension 2324 2325Property Immutable Mandatory since 2326──────── ───────── ─────────────── 2327non-desktop yes not mandatory 2328 2329 ❧❧❧❧❧❧❧❧❧❧❧ 2330 233110. Extension Versioning 2332 2333The RandR extension was developed in parallel with the implementation 2334to ensure the feasibility of various portions of the design. As 2335portions of the extension are implemented, the version number of the 2336extension has changed to reflect the portions of the standard provided. 2337This document describes the version 1.4 of the specification, the 2338partial implementations have version numbers less than that. Here's a 2339list of what each version provided: 2340 2341 0.0: This prototype implemented resize and rotation in the 2342 TinyX server Used approximately the protocol described in 2343 the Usenix paper. Appeared in the TinyX server in 2344 XFree86 4.2, but not in the XFree86 main server. 2345 2346 0.1: Added subpixel order, added an event for subpixel order. 2347 This version was never checked in to XFree86 CVS. 2348 2349 1.0: Implements resize, rotation, and reflection. Implemented 2350 both in the XFree86 main server (size change only at this 2351 date), and fully (size change, rotation, and reflection) 2352 in XFree86's TinyX server. 2353 2354 1.1: Added refresh rates 2355 2356 1.2: Separate screens from CRTCs and outputs, switch to full VESA 2357 modes 2358 2359 1.3: Added cheap version of RRGetScreenResources. Added CRTC 2360 transformations. Added panning. Added primary outputs. 2361 Added standard properties. 2362 2363 1.4: Added provider objects for handling multi-GPU systems. 2364 2365 1.5: Added Monitors 2366 2367 1.6: Added Leases and non-desktop output information. 2368 2369Compatibility between 0.0 and 1.0 was *NOT* preserved, and 0.0 clients 2370will fail against 1.0 servers. The wire encoding op-codes were 2371changed for GetScreenInfo to ensure this failure in a relatively 2372graceful way. Version 1.1 servers and clients are cross compatible with 23731.0. Version 1.1 is considered to be stable and we intend upward 2374compatibility from this point. Version 1.2 offers an extended model of the 2375system with multiple output support. Version 1.3 adds a cheap version of 2376GetScreenResources to avoid expensive DDC operations, CRTC transformations, 2377panning, and the primary output concept. Versions 1.2 through 1.6 are 2378backward-compatible with 1.1. 2379 2380 ❧❧❧❧❧❧❧❧❧❧❧ 2381 238211. Relationship with other extensions 2383 2384Two other extensions have a direct relationship with this extension. This 2385section attempts to explain how these three are supposed to work together. 2386 238711.1 XFree86-VidModeExtension 2388 2389XFree86-VidModeExtension changes the configuration of a single monitor 2390attached to the screen without changing the configuration of the screen 2391itself. It provides the ability to specify new mode lines for the server to 2392use along with selecting among existing mode lines. As it uses screen 2393numbers instead of window identifiers, it can be used to affect multiple 2394monitors in a single-screen Xinerama configuration. However, the association 2395between screen numbers and root windows in a multi-Screen environment is not 2396defined by the extension. Version 2.0 of this extension added the ability to 2397adjust the DAC values in a TrueColor server to modify the brightness curves 2398of the display. 2399 2400All of the utility of this extension is subsumed by RandR version 1.2, RandR 2401should be used in preference to XFree86-VidModeExtension where both are 2402present. 2403 240411.2 Xinerama 2405 2406Xinerama provides a mechanism for describing the relationship between the 2407overall screen display and monitors placed within that area. As such, it 2408provides the query functionality of RandR 1.2 without any of the 2409configuration functionality. Applications using Xinerama to discover 2410monitor geometry can continue to do so, with the caveat that they will not be 2411informed of changes when they occur. However, Xinerama configuration data 2412will be updated, so applications selecting for RandR notification and 2413re-querying the configuration with the Xinerama extension will get updated 2414information. It is probably better to view RandR as a superset of Xinerama 2415at this point and use it in preference to Xinerama where both are present. 2416 2417 ❧❧❧❧❧❧❧❧❧❧❧ 2418 2419Appendix A. Protocol Encoding 2420 2421Syntactic Conventions 2422 2423This document uses the same syntactic conventions as the core X 2424protocol encoding document. 2425 2426A.1 Common Types 2427 2428┌─── 2429 ROTATION 2430 0x0001 Rotate_0 2431 0x0002 Rotate_90 2432 0x0004 Rotate_180 2433 0x0008 Rotate_270 2434 0x0010 Reflect_X 2435 0x0020 Reflect_Y 2436└─── 2437 Used to encode both sets of possible rotations and individual 2438 selected rotations. 2439 2440┌─── 2441 RRSELECTMASK 2442 0x0001 ScreenChangeNotifyMask 2443 0x0002 CrtcChangeNotifyMask Added in version 1.2 2444 0x0004 OutputChangeNotifyMask Added in version 1.2 2445 0x0008 OutputPropertyNotifyMask Added in version 1.2 2446 0x0010 ProviderChangeNotifyMask Added in version 1.4 2447 0x0020 ProviderPropertyNotifyMask Added in version 1.4 2448 0x0040 ResourceChangeNotifyMask Added in version 1.4 2449 0x0080 LeaseNotifyMask Added in version 1.6 2450 2451└─── 2452 Event select mask for RRSelectInput 2453 2454┌─── 2455 RRCONFIGSTATUS 2456 0x0 Success 2457 0x1 InvalidConfigTime 2458 0x2 InvalidTime 2459 0x3 Failed 2460└─── 2461 Return status for requests which depend on time. 2462 2463┌─── 2464 MODEINFO (32) Added in version 1.2 2465 4 CARD32 id 2466 2 CARD16 width in pixels 2467 2 CARD16 height in pixels 2468 4 CARD32 dot clock 2469 2 CARD16 h sync start 2470 2 CARD16 h sync end 2471 2 CARD16 h total 2472 2 CARD16 h skew 2473 2 CARD16 v sync start 2474 2 CARD16 v sync end 2475 2 CARD16 v total 2476 2 CARD16 name length 2477 4 SETofMODEFLAG mode flags 2478└─── 2479 2480 An output mode specifies the complete CRTC timings for 2481 a specific mode. The vertical and horizontal synchronization rates 2482 can be computed given the dot clock and the h total/v total 2483 values. If the dot clock is zero, then all of the timing 2484 parameters and flags are not used, and must be zero as this 2485 indicates that the timings are unknown or otherwise unused. 2486 The name itself will be encoded separately in each usage. 2487 2488┌─── 2489 MODEFLAG 2490 0x00000001 HSyncPositive 2491 0x00000002 HSyncNegative 2492 0x00000004 VSyncPositive 2493 0x00000008 VSyncNegative 2494 0x00000010 Interlace 2495 0x00000020 DoubleScan 2496 0x00000040 CSync 2497 0x00000080 CSyncPositive 2498 0x00000100 CSyncNegative 2499 0x00000200 HSkewPresent 2500 0x00000400 BCast 2501 0x00000800 PixelMultiplex 2502 0x00001000 DoubleClock 2503 0x00002000 ClockDivideBy2 2504└─── 2505┌─── 2506 CONNECTION 2507 0 Connected 2508 1 Disconnected 2509 2 UnknownConnection 2510└─── 2511 2512┌─── 2513 PROVIDER_CAPS Added in version 1.4 2514 0x00000001 SourceOutput 2515 0x00000002 SinkOutput 2516 0x00000004 SourceOffload 2517 0x00000008 SinkOffload 2518└─── 2519 2520A.1.1 Common Types added in version 1.5 of the protocol 2521 2522┌─── 2523 MONITORINFO (16 + 4*n) 2524 4 ATOM name 2525 1 BOOL primary 2526 1 BOOL automatic 2527 2 CARD16 noutputs 2528 2 INT16 x 2529 2 INT16 y 2530 2 CARD16 width in pixels 2531 2 CARD16 height in pixels 2532 4 CARD32 width in millimeters 2533 4 CARD32 height in millimeters 2534 4*n OUTPUT outputs 2535└─── 2536 2537A.2 Protocol Requests 2538 2539Opcodes 1 and 3 were used in the 0.0 protocols, and will return 2540errors if used in version 1.0. 2541 2542┌─── 2543 RRQueryVersion 2544 2545 1 CARD8 major opcode 2546 1 0 RandR opcode 2547 2 3 length 2548 4 CARD32 major version 2549 4 CARD32 minor version 2550 ▶ 2551 1 1 Reply 2552 1 unused 2553 2 CARD16 sequence number 2554 4 0 reply length 2555 1 CARD32 major version 2556 1 CARD32 minor version 2557└─── 2558┌─── 2559 RRSetScreenConfig 2560 2561 1 CARD8 major opcode 2562 1 2 RandR opcode 2563 2 6 length 2564 4 WINDOW window on screen to be configured 2565 4 TIMESTAMP timestamp 2566 4 TIMESTAMP config timestamp 2567 2 SIZEID size index 2568 2 ROTATION rotation/reflection 2569 2 CARD16 refresh rate (1.1 only) 2570 2 CARD16 pad 2571 ▶ 2572 1 1 Reply 2573 1 RRCONFIGSTATUS status 2574 2 CARD16 sequence number 2575 4 0 reply length 2576 4 TIMESTAMP new timestamp 2577 4 TIMESTAMP new configuration timestamp 2578 4 WINDOW root 2579 2 SUBPIXELORDER subpixel order defined in Render 2580 2 CARD16 pad4 2581 4 CARD32 pad5 2582 4 CARD32 pad6 2583└─── 2584┌─── 2585 RRSelectInput 2586 2587 1 CARD8 major opcode 2588 1 4 RandR opcode 2589 2 3 length 2590 4 WINDOW window 2591 2 SETofRRSELECTMASK enable 2592 2 CARD16 pad 2593└─── 2594┌─── 2595 RRGetScreenInfo 2596 2597 1 CARD8 major opcode 2598 1 5 RandR opcode 2599 2 2 length 2600 4 WINDOW window 2601 ▶ 2602 1 1 Reply 2603 1 CARD8 set of Rotations 2604 2 CARD16 sequence number 2605 4 0 reply length 2606 4 WINDOW root window 2607 4 TIMESTAMP timestamp 2608 4 TIMESTAMP config timestamp 2609 2 CARD16 number of SCREENSIZE following 2610 2 SIZEID current size index 2611 2 ROTATION current rotation and reflection 2612 2 CARD16 current rate (added in version 1.1) 2613 2 CARD16 length of rate info (number of CARD16s) 2614 2 CARD16 pad 2615 2616 SCREENSIZE 2617 2 CARD16 width in pixels 2618 2 CARD16 height in pixels 2619 2 CARD16 width in millimeters 2620 2 CARD16 height in millimeters 2621 2622 REFRESH 2623 2 CARD16 number of rates (n) 2624 2n CARD16 rates 2625└─── 2626 2627A.2.1 Protocol Requests added with version 1.2 2628 2629┌─── 2630 RRGetScreenSizeRange 2631 1 CARD8 major opcode 2632 1 6 RandR opcode 2633 2 2 length 2634 4 WINDOW window 2635 ▶ 2636 1 1 Reply 2637 1 unused 2638 2 CARD16 sequence number 2639 4 0 reply length 2640 2 CARD16 minWidth 2641 2 CARD16 minHeight 2642 2 CARD16 maxWidth 2643 2 CARD16 maxHeight 2644 16 unused 2645└─── 2646┌─── 2647 RRSetScreenSize 2648 1 CARD8 major opcode 2649 1 7 RandR opcode 2650 2 5 length 2651 4 WINDOW window 2652 2 CARD16 width 2653 2 CARD16 height 2654 4 CARD32 width in millimeters 2655 4 CARD32 height in millimeters 2656└─── 2657┌─── 2658 RRGetScreenResources 2659 1 CARD8 major opcode 2660 1 8 RandR opcode 2661 2 2 length 2662 4 WINDOW window 2663 ▶ 2664 1 1 Reply 2665 1 unused 2666 2 CARD16 sequence number 2667 4 c+o+8m+(b+p)/4 reply length 2668 4 TIMESTAMP timestamp 2669 4 TIMESTAMP config-timestamp 2670 2 c number of CRTCs 2671 2 o number of outputs 2672 2 m number of modeinfos 2673 2 b total bytes in mode names 2674 8 unused 2675 4c LISTofCRTC crtcs 2676 4o LISTofOUTPUT outputs 2677 32m LISTofMODEINFO modeinfos 2678 b STRING8 mode names 2679 p unused, p=pad(b) 2680└─── 2681┌─── 2682 RRGetOutputInfo 2683 1 CARD8 major opcode 2684 1 9 RandR opcode 2685 2 3 length 2686 4 OUTPUT output 2687 4 TIMESTAMP config-timestamp 2688 ▶ 2689 1 1 Reply 2690 1 RRCONFIGSTATUS status 2691 2 CARD16 sequence number 2692 4 1+c+m+(n+p)/4 reply length 2693 4 TIMESTAMP timestamp 2694 4 CRTC current connected crtc 2695 4 CARD32 width in millimeters 2696 4 CARD32 height in millimeters 2697 1 CONNECTION connection 2698 1 SUBPIXELORDER subpixel-order 2699 2 c number of CRTCs 2700 2 m number of modes 2701 2 p number of preferred modes 2702 2 o number of clones 2703 2 n length of name 2704 4c LISTofCRTC crtcs 2705 4m LISTofMODE modes 2706 4o LISTofOUTPUT clones 2707 n STRING8 name 2708 p unused, p=pad(n) 2709└─── 2710┌─── 2711 RRListOutputProperties 2712 1 CARD8 major opcode 2713 1 10 RandR opcode 2714 2 2 length 2715 4 OUTPUT output 2716 ▶ 2717 1 1 Reply 2718 1 unused 2719 2 CARD16 sequence number 2720 4 n reply length 2721 2 n number of ATOMs in atoms 2722 22 unused 2723 4n LISTofATOM atoms 2724└─── 2725┌─── 2726 RRQueryOutputProperty 2727 1 CARD8 major opcode 2728 1 11 RandR opcode 2729 2 3 request length 2730 4 OUTPUT output 2731 4 ATOM property 2732 ▶ 2733 1 1 Reply 2734 1 unused 2735 2 CARD16 sequence number 2736 4 n reply length 2737 1 BOOL pending 2738 1 BOOL range 2739 1 BOOL immutable 2740 21 unused 2741 4n LISTofINT32 valid values 2742└─── 2743┌─── 2744 RRConfigureOutputProperty 2745 1 CARD8 major opcode 2746 1 12 RandR opcode 2747 2 4+n request length 2748 4 OUTPUT output 2749 4 ATOM property 2750 1 BOOL pending 2751 1 BOOL range 2752 2 unused 2753 4n LISTofINT32 valid values 2754└─── 2755┌─── 2756 RRChangeOutputProperty 2757 1 CARD8 major opcode 2758 1 13 RandR opcode 2759 2 6+(n+p)/4 request length 2760 4 OUTPUT output 2761 4 ATOM property 2762 4 ATOM type 2763 1 CARD8 format 2764 1 mode 2765 0 Replace 2766 1 Prepend 2767 2 Append 2768 2 unused 2769 4 CARD32 length of data in format units 2770 (= n for format = 8) 2771 (= n/2 for format = 16) 2772 (= n/4 for format = 32) 2773 n LISTofBYTE data 2774 (n is a multiple of 2 for format = 16) 2775 (n is a multiple of 4 for format = 32) 2776 p unused, p=pad(n) 2777└─── 2778┌─── 2779 RRDeleteOutputProperty 2780 1 CARD8 major opcode 2781 1 14 RandR opcode 2782 2 3 request length 2783 4 OUTPUT output 2784 4 ATOM property 2785└─── 2786┌─── 2787 RRGetOutputProperty 2788 1 CARD8 major opcode 2789 1 15 RandR opcode 2790 2 7 request length 2791 4 OUTPUT output 2792 4 ATOM property 2793 4 ATOM type 2794 0 AnyPropertyType 2795 4 CARD32 long-offset 2796 4 CARD32 long-length 2797 1 BOOL delete 2798 1 BOOL pending 2799 2 unused 2800 ▶ 2801 1 1 Reply 2802 1 CARD8 format 2803 2 CARD16 sequence number 2804 4 (n+p)/4 reply length 2805 4 ATOM type 2806 0 None 2807 4 CARD32 bytes-after 2808 4 CARD32 length of value in format units 2809 (= 0 for format = 0) 2810 (= n for format = 8) 2811 (= n/2 for format = 16) 2812 (= n/4 for format = 32) 2813 12 unused 2814 n LISTofBYTE value 2815 (n is zero for format = 0) 2816 (n is a multiple of 2 for format = 16) 2817 (n is a multiple of 4 for format = 32) 2818 p unused, p=pad(n) 2819└─── 2820┌─── 2821 RRCreateMode 2822 1 CARD8 major opcode 2823 1 16 RandR opcode 2824 2 10+(n+p)/4 length 2825 4 WINDOW window 2826 32 MODEINFO mode 2827 n STRING8 mode name 2828 p unused, p=pad(n) 2829 ▶ 2830 1 1 Reply 2831 1 unused 2832 2 CARD16 sequence number 2833 4 0 reply length 2834 4 MODE mode 2835 20 unused 2836└─── 2837┌─── 2838 RRDestroyMode 2839 1 CARD8 major opcode 2840 1 17 RandR opcode 2841 2 2 length 2842 4 MODE mode 2843└─── 2844┌─── 2845 RRAddOutputMode 2846 1 CARD8 major opcode 2847 1 18 RandR opcode 2848 2 3 length 2849 4 OUTPUT output 2850 4 MODE mode 2851└─── 2852┌─── 2853 RRDeleteOutputMode 2854 1 CARD8 major opcode 2855 1 19 RandR opcode 2856 2 3 length 2857 4 OUTPUT output 2858 4 MODE mode 2859└─── 2860┌─── 2861 RRGetCrtcInfo 2862 1 CARD8 major opcode 2863 1 20 RandR opcode 2864 2 3 length 2865 4 CRTC crtc 2866 4 TIMESTAMP config-timestamp 2867 ▶ 2868 1 1 Reply 2869 1 RRCONFIGSTATUS status 2870 2 CARD16 sequence number 2871 4 o+p reply length 2872 4 TIMESTAMP timestamp 2873 2 INT16 x 2874 2 INT16 y 2875 2 CARD16 width 2876 2 CARD16 height 2877 4 MODE mode 2878 2 ROTATION current rotation and reflection 2879 2 ROTATION set of possible rotations 2880 2 o number of outputs 2881 2 p number of possible outputs 2882 4o LISTofOUTPUT outputs 2883 4p LISTofOUTPUT possible outputs 2884└─── 2885┌─── 2886 RRSetCrtcConfig 2887 1 CARD8 major opcode 2888 1 21 RandR opcode 2889 2 7+n length 2890 4 CRTC crtc 2891 4 TIMESTAMP timestamp 2892 4 TIMESTAMP config timestamp 2893 2 INT16 x 2894 2 INT16 y 2895 4 MODE mode 2896 2 ROTATION rotation/reflection 2897 2 unused 2898 4n LISTofOUTPUT outputs 2899 ▶ 2900 1 1 Reply 2901 1 RRCONFIGSTATUS status 2902 2 CARD16 sequence number 2903 4 0 reply length 2904 4 TIMESTAMP new timestamp 2905 20 unused 2906└─── 2907┌─── 2908 RRGetCrtcGammaSize 2909 1 CARD8 major opcode 2910 1 22 RandR opcode 2911 2 2 length 2912 4 CRTC crtc 2913 ▶ 2914 1 1 Reply 2915 1 unused 2916 2 CARD16 sequence number 2917 4 0 reply length 2918 2 CARD16 size 2919 22 unused 2920└─── 2921┌─── 2922 RRGetCrtcGamma 2923 1 CARD8 major opcode 2924 1 23 RandR opcode 2925 2 2 length 2926 4 CRTC crtc 2927 ▶ 2928 1 1 Reply 2929 1 unused 2930 2 CARD16 sequence number 2931 4 (6n+p)/4 reply length 2932 2 n size 2933 20 unused 2934 2n LISTofCARD16 red 2935 2n LISTofCARD16 green 2936 2n LISTofCARD16 blue 2937 p unused, p=pad(6n) 2938└─── 2939┌─── 2940 RRSetCrtcGamma 2941 1 CARD8 major opcode 2942 1 24 RandR opcode 2943 2 3+(6n+p)/4 length 2944 4 CRTC crtc 2945 2 n size 2946 2 unused 2947 2n LISTofCARD16 red 2948 2n LISTofCARD16 green 2949 2n LISTofCARD16 blue 2950 p unused, p=pad(6n) 2951└─── 2952 2953A.2.2 Protocol Requests added with version 1.3 2954 2955┌─── 2956 RRGetScreenResourcesCurrent 2957 1 CARD8 major opcode 2958 1 25 RandR opcode 2959 2 2 length 2960 4 WINDOW window 2961 ▶ 2962 1 1 Reply 2963 1 unused 2964 2 CARD16 sequence number 2965 4 c+o+8m+(b+p)/4 reply length 2966 4 TIMESTAMP timestamp 2967 4 TIMESTAMP config-timestamp 2968 2 c number of CRTCs 2969 2 o number of outputs 2970 2 m number of modeinfos 2971 2 b total bytes in mode names 2972 8 unused 2973 4c LISTofCRTC crtcs 2974 4o LISTofOUTPUT outputs 2975 32m LISTofMODEINFO modeinfos 2976 b STRING8 mode names 2977 p unused, p=pad(b) 2978└─── 2979 2980┌─── 2981 RRSetCrtcTransform 2982 1 CARD8 major opcode 2983 1 26 RandR opcode 2984 2 12+(n+p)/4+v length 2985 4 CRTC crtc 2986 36 TRANSFORM transform 2987 2 CARD16 filter length 2988 2 unused 2989 n STRING8 filter name 2990 p unused, p=pad(n) 2991 4v FIXED filter params 2992└─── 2993 2994┌─── 2995 RRGetCrtcTransform 2996 1 CARD8 major opcode 2997 1 27 RandR opcode 2998 2 2 length 2999 4 CRTC crtc 3000 ▶ 3001 1 1 Reply 3002 1 unused 3003 2 CARD16 sequence number 3004 4 16+(pn+pnp)/4+(cn+cnp)/4+pf+cf reply length 3005 36 TRANSFORM pending transform 3006 1 BOOL has transforms 3007 3 unused 3008 36 TRANSFORM current transform 3009 4 unused 3010 2 pn pending filter name length 3011 2 pf pending filter num params 3012 2 cn current filter name length 3013 2 cf current filter num params 3014 pn STRING8 pending filter name 3015 pnp unused, pnp=pad(pn) 3016 4*pf FIXED pending filter params 3017 cn STRING8 current filter name 3018 cnp unused, cnp=pad(cn) 3019 4*cf FIXED current filter params 3020└─── 3021 3022┌─── 3023 RRGetPanning 3024 1 CARD8 major opcode 3025 1 28 RandR opcode 3026 2 2 length 3027 4 CRTC crtc 3028 ▶ 3029 1 1 Reply 3030 1 RRCONFIGSTATUS status 3031 2 CARD16 sequence number 3032 4 1 reply length 3033 4 TIMESTAMP timestamp 3034 2 CARD16 left 3035 2 CARD16 top 3036 2 CARD16 width 3037 2 CARD16 height 3038 2 CARD16 track_left 3039 2 CARD16 track_top 3040 2 CARD16 track_width 3041 2 CARD16 track_height 3042 2 INT16 border_left 3043 2 INT16 border_top 3044 2 INT16 border_right 3045 2 INT16 border_bottom 3046└─── 3047┌─── 3048 RRSetPanning 3049 1 CARD8 major opcode 3050 1 29 RandR opcode 3051 2 9 length 3052 4 CRTC crtc 3053 4 TIMESTAMP timestamp 3054 2 CARD16 left 3055 2 CARD16 top 3056 2 CARD16 width 3057 2 CARD16 height 3058 2 CARD16 track_left 3059 2 CARD16 track_top 3060 2 CARD16 track_width 3061 2 CARD16 track_height 3062 2 INT16 border_left 3063 2 INT16 border_top 3064 2 INT16 border_right 3065 2 INT16 border_bottom 3066 ▶ 3067 1 1 Reply 3068 1 RRCONFIGSTATUS status 3069 2 CARD16 sequence number 3070 4 0 reply length 3071 4 TIMESTAMP new timestamp 3072 20 unused 3073└─── 3074 3075┌─── 3076 RRSetOutputPrimary 3077 1 CARD8 major opcode 3078 1 30 RandR opcode 3079 2 3 length 3080 4 WINDOW window 3081 4 OUTPUT output 3082└─── 3083 3084┌─── 3085 RRGetOutputPrimary 3086 1 CARD8 major opcode 3087 1 31 RandR opcode 3088 2 2 length 3089 4 WINDOW window 3090 ▶ 3091 1 1 Reply 3092 1 unused 3093 2 CARD16 sequence number 3094 4 CARD32 length 3095 4 OUTPUT output 3096 4 CARD32 pad1 3097 4 CARD32 pad2 3098 4 CARD32 pad3 3099 4 CARD32 pad4 3100└─── 3101 3102A.2.3 Protocol Requests added with version 1.4 3103 3104┌─── 3105 RRGetProviders 3106 1 CARD8 major opcode 3107 1 32 RandR opcode 3108 2 2 length 3109 4 WINDOW window 3110 ▶ 3111 1 1 Reply 3112 1 unused 3113 2 CARD16 sequence number 3114 4 p length 3115 4 TIMESTAMP timestamp 3116 2 p number of Providers 3117 18 unused 3118 4p LISTofPROVIDERS providers 3119└─── 3120┌─── 3121 RRGetProviderInfo 3122 1 CARD8 major opcode 3123 1 33 RandR opcode 3124 2 3 length 3125 4 PROVIDER provider 3126 4 TIMESTAMP config-timestamp 3127 ▶ 3128 1 1 Reply 3129 1 RRCONFIGSTATUS status 3130 2 CARD16 sequence number 3131 4 1+c+o+(a*2)+(n+p)/4 reply length 3132 4 TIMESTAMP timestamp 3133 4 CARD32 capabilities 3134 2 c number of crtcs 3135 2 o number of outputs 3136 2 a number of associated providers 3137 2 n length of name 3138 8 unused 3139 4c LISTofCRTC crtcs 3140 4o LISTofOUTPUT outputs 3141 4a LISTofPROVIDER associated providers 3142 4a CARD32 associated provider capability 3143 n STRING8 name 3144 p unused, p=pad(n) 3145└─── 3146┌─── 3147 RRSetProviderOffloadSink 3148 1 CARD8 major opcode 3149 1 34 RandR opcode 3150 2 4 length 3151 4 PROVIDER provider 3152 4 PROVIDER offload sink provider 3153 4 TIMESTAMP timestamp 3154└─── 3155┌─── 3156 RRSetProviderOutputSource 3157 1 CARD8 major opcode 3158 1 35 RandR opcode 3159 2 4 length 3160 4 PROVIDER provider 3161 4 PROVIDER output source provider 3162 4 TIMESTAMP timestamp 3163└─── 3164┌─── 3165 RRListProviderProperties 3166 1 CARD8 major opcode 3167 1 36 RandR opcode 3168 2 2 length 3169 4 PROVIDER provider 3170 ▶ 3171 1 1 Reply 3172 1 unused 3173 2 CARD16 sequence number 3174 4 n reply length 3175 2 n number of ATOMs in atoms 3176 22 unused 3177 4n LISTofATOM atoms 3178└─── 3179┌─── 3180 RRQueryProviderProperty 3181 1 CARD8 major opcode 3182 1 37 RandR opcode 3183 2 3 request length 3184 4 PROVIDER provider 3185 4 ATOM property 3186 ▶ 3187 1 1 Reply 3188 1 unused 3189 2 CARD16 sequence number 3190 4 n reply length 3191 1 BOOL pending 3192 1 BOOL range 3193 1 BOOL immutable 3194 21 unused 3195 4n LISTofINT32 valid values 3196└─── 3197┌─── 3198 RRConfigureProviderProperty 3199 1 CARD8 major opcode 3200 1 38 RandR opcode 3201 2 4+n request length 3202 4 PROVIDER provider 3203 4 ATOM property 3204 1 BOOL pending 3205 1 BOOL range 3206 2 unused 3207 4n LISTofINT32 valid values 3208└─── 3209┌─── 3210 RRChangeProviderProperty 3211 1 CARD8 major opcode 3212 1 39 RandR opcode 3213 2 6+(n+p)/4 request length 3214 4 PROVIDER provider 3215 4 ATOM property 3216 4 ATOM type 3217 1 CARD8 format 3218 1 mode 3219 0 Replace 3220 1 Prepend 3221 2 Append 3222 2 unused 3223 4 CARD32 length of data in format units 3224 (= n for format = 8) 3225 (= n/2 for format = 16) 3226 (= n/4 for format = 32) 3227 n LISTofBYTE data 3228 (n is a multiple of 2 for format = 16) 3229 (n is a multiple of 4 for format = 32) 3230 p unused, p=pad(n) 3231└─── 3232┌─── 3233 RRDeleteProviderProperty 3234 1 CARD8 major opcode 3235 1 40 RandR opcode 3236 2 3 request length 3237 4 PROVIDER provider 3238 4 ATOM property 3239└─── 3240┌─── 3241 RRGetProviderProperty 3242 1 CARD8 major opcode 3243 1 41 RandR opcode 3244 2 7 request length 3245 4 PROVIDER provider 3246 4 ATOM property 3247 4 ATOM type 3248 0 AnyPropertyType 3249 4 CARD32 long-offset 3250 4 CARD32 long-length 3251 1 BOOL delete 3252 1 BOOL pending 3253 2 unused 3254 ▶ 3255 1 1 Reply 3256 1 CARD8 format 3257 2 CARD16 sequence number 3258 4 (n+p)/4 reply length 3259 4 ATOM type 3260 0 None 3261 4 CARD32 bytes-after 3262 4 CARD32 length of value in format units 3263 (= 0 for format = 0) 3264 (= n for format = 8) 3265 (= n/2 for format = 16) 3266 (= n/4 for format = 32) 3267 12 unused 3268 n LISTofBYTE value 3269 (n is zero for format = 0) 3270 (n is a multiple of 2 for format = 16) 3271 (n is a multiple of 4 for format = 32) 3272 p unused, p=pad(n) 3273└─── 3274 3275A.2.4 Protocol Requests added with version 1.5 3276 3277┌─── 3278 RRGetMonitors 3279 1 CARD8 major opcode 3280 1 42 RandR opcode 3281 2 2 request length 3282 4 WINDOW window 3283 ▶ 3284 1 1 Reply 3285 1 unused 3286 2 CARD16 sequence number 3287 4 6*n + o reply length 3288 4 TIMESTAMP timestamp 3289 4 n nmonitors 3290 4 o noutputs 3291 12 unused 3292 n*24+o*4 LISTofMONITORINFO monitors 3293└─── 3294┌─── 3295 RRSetMonitor 3296 1 CARD8 major opcode 3297 1 43 RandR opcode 3298 2 6 + o request length 3299 4 WINDOW window 3300 24+o MONITORINFO monitorinfo 3301└─── 3302┌─── 3303 RRDeleteMonitor 3304 1 CARD8 major opcode 3305 1 44 RandR opcode 3306 2 3 request length 3307 4 WINDOW window 3308 4 ATOM name 3309└─── 3310 3311A.3 Protocol Events 3312 3313┌─── 3314 RRScreenChangeNotify 3315 1 Base + 0 code 3316 1 ROTATION new rotation and reflection 3317 2 CARD16 sequence number 3318 4 TIMESTAMP timestamp 3319 4 TIMESTAMP configuration timestamp 3320 4 WINDOW root window 3321 4 WINDOW request window 3322 2 SIZEID size ID 3323 2 SUBPIXELORDER subpixel order defined in Render 3324 2 CARD16 width in pixels 3325 2 CARD16 height in pixels 3326 2 CARD16 width in millimeters 3327 2 CARD16 height in millimeters 3328└─── 3329 3330A.3.1 Protocol Events added with version 1.2 3331 3332┌─── 3333 RRCrtcChangeNotify 3334 1 Base + 1 code 3335 1 0 sub-code 3336 2 CARD16 sequence number 3337 4 TIMESTAMP timestamp 3338 4 WINDOW request window 3339 4 CRTC crtc affected 3340 4 MODE mode in use 3341 2 ROTATION new rotation and reflection 3342 2 unused 3343 2 INT16 x 3344 2 INT16 y 3345 2 CARD16 width 3346 2 CARD16 height 3347└─── 3348┌─── 3349 RROutputChangeNotify 3350 1 Base + 1 code 3351 1 1 sub-code 3352 2 CARD16 sequence number 3353 4 TIMESTAMP timestamp 3354 4 TIMESTAMP configuration timestamp 3355 4 WINDOW request window 3356 4 OUTPUT output affected 3357 4 CRTC crtc in use 3358 4 MODE mode in use 3359 2 ROTATION rotation in use 3360 1 CONNECTION connection status 3361 1 SUBPIXELORDER subpixel order 3362└─── 3363┌─── 3364 RROutputPropertyNotify 3365 1 Base + 1 code 3366 1 2 sub-code 3367 2 CARD16 sequence number 3368 4 WINDOW window 3369 4 OUTPUT output 3370 4 ATOM atom 3371 4 TIMESTAMP time 3372 1 state 3373 0 NewValue 3374 1 Deleted 3375 11 unused 3376└─── 3377 3378A.3.2 Protocol Events added with version 1.4 3379┌─── 3380 RRProviderChangeNotify 3381 1 Base + 1 code 3382 1 3 sub-code 3383 2 CARD16 sequence number 3384 4 TIMESTAMP timestamp 3385 4 WINDOW request window 3386 4 PROVIDER provider affected 3387 16 unused 3388└─── 3389┌─── 3390 RRProviderPropertyNotify 3391 1 Base + 1 code 3392 1 4 sub-code 3393 2 CARD16 sequence number 3394 4 WINDOW window 3395 4 PROVIDER provider 3396 4 ATOM atom 3397 4 TIMESTAMP time 3398 1 state 3399 0 NewValue 3400 1 Deleted 3401 11 unused 3402└─── 3403┌─── 3404 RRResourceChangeNotify 3405 1 Base + 1 code 3406 1 5 sub-code 3407 2 CARD16 sequence number 3408 4 TIMESTAMP time 3409 4 WINDOW window 3410 20 unused 3411└─── 3412A.4 Protocol Errors 3413 3414┌─── 3415 ERRORS 3416 Base + 0 Output 3417 Base + 1 Crtc 3418 Base + 2 Mode 3419 Base + 3 Provider 3420└─── 3421 3422Bibliography 3423 3424[RANDR] Gettys, Jim and Keith Packard, "The X Resize and Rotate 3425 Extension - RandR", Proceedings of the 2001 USENIX Annual 3426 Technical Conference, Boston, MA 3427 3428[RENDER] 3429 Packard, Keith, "The X Rendering Extension", work in progress, 3430 http://cgit.freedesktop.org/xorg/proto/renderproto/tree/renderproto.txt 3431