The X Resize, Rotate and Reflect Extension Version 1.2 2006-4-13 Jim Gettys Jim.Gettys@hp.com Cambridge Research Laboratory HP Labs Hewlett Packard Company Keith Packard keith.packard@intel.com Open Source Technology Center Intel Corporation 1. Introduction The X Resize, Rotate and Reflect Extension, called RandR for short, brings the ability to resize, rotate and reflect the root window of a screen. It is based on the X Resize and Rotate Extension as specified in the Proceedings of the 2001 Usenix Technical Conference [RANDR]. RandR as implemented and integrated into the X server differs in one substantial fashion from the design discussed in that paper: that is, RandR 1.0 does not implement the depth switching described in that document, and the support described for that in the protocol in that document and in the implementation has been removed from the protocol described here, as it has been overtaken by events. These events include: ► Modern toolkits (in this case, GTK+ 2.x) have progressed to the point of implementing migration between screens of arbitrary depths ► The continued advance of Moore's law has made limited amounts of VRAM less of an issue, reducing the pressure to implement depth switching on laptops or desktop systems ► The continued decline of legacy toolkits whose design would have required depth switching to support migration ► The lack of depth switching implementation experience in the intervening time, due to events beyond our control Additionally, the requirement to support depth switching might complicate other re-engineering of the device independent part of the X server that is currently being contemplated. Rather than further delaying RandR's widespread deployment for a feature long wanted by the community (resizing of screens, particularly on laptops), or the deployment of a protocol design that might be flawed due to lack of implementation experience, we decided to remove depth switching from the protocol. It may be implemented at a later time if resources and interests permit as a revision to the protocol described here, which will remain a stable base for applications. The protocol described here has been implemented in the main X.org server, and more fully in the hw/kdrive implementation in the distribution, which fully implements resizing, rotation and reflection. 1.2 Introduction to version 1.2 of the extension One of the significant limitations found in version 1.1 of the RandR protocol was the inability to deal with the Xinerama model where multiple monitors display portions of a common underlying screen. In this environment, zero or more video outputs are associated with each CRT controller which defines both a set of video timings and a 'viewport' within the larger screen. This viewport is independent of the overall size of the screen, and may be located anywhere within the screen. The effect is to decouple the reported size of the screen from the size presented by each video output, and to permit multiple outputs to present information for a single screen. To extend RandR for this model, we separate out the output, CRTC and screen configuration information and permit them to be configured separately. For compatibility with the 1.1 version of the protocol, we make the 1.1 requests simultaneously affect both the screen and the (presumably sole) CRTC and output. The set of available outputs are presented with UTF-8 encoded names and may be connected to CRTCs as permitted by the underlying hardware. CRTC configuration is now done with full mode information instead of just size and refresh rate, and these modes have names. These names also use UTF-8 encoding. New modes may also be added by the user. Additional requests and events are provided for this new functionality. ┌────────────────────────────────┬──────────┐ ┏━━━━━━━┳───────────────┐ ╔════════╗ ╔════════╗ ┃ 1 ┃ │ ║ A ║ ║ B ║ ┃ ┏━━━╋━━━━━━━━━━━━━━━┫ ║ ║ ║ ║ ┣━━━╋━━━┛ ┃ ╚════════╝ ╚════════╝ │ ┃ 2 ┃─────────────────┐ │ ┃ ┃ ╔═══════════════════╗ │ ┃ ┃ ║ ║ │ ┗━━━━━━━━━━━━━━━━━━━┫ ║ C ║ └───────────────────────┘ ║ ║ ┌──────┐ ┏━━━━┓ ╔══════╗ ║ ║ │screen│ ┃CRTC┃ ║output║ ╚═══════════════════╝ └──────┘ ┗━━━━┛ ╚══════╝ In this picture, the screen is covered (incompletely) by two CRTCs. CRTC1 is connected to two outputs, A and B. CRTC2 is connected to output C. Outputs A and B will present exactly the same region of the screen using the same mode line. Output C will present a different (larger) region of the screen using a different mode line. RandR provides information about each available CRTC and output; the connection between CRTC and output is under application control, although the hardware will probably impose restrictions on the possible configurations. The protocol doesn't try to describe these restrictions, instead it provides a mechanism to find out what combinations are supported. For instance, dual-link DVI gangs two CRTC outputs together to provide higher bandwidth for large resolution screens. This is exposed in RandR by requiring that nothing be connected to the second CRTC when driving a high resolution screen on the first. 1.1 Acknowledgements Our thanks to the contributors to the design found on the xpert mailing list, in particular: Alan Hourihane for work on the early implementation Andrew C. Aitchison for help with the XFree86 DDX implementation Andy Ritger for early questions about how mergefb/Xinerama work with RandR Carl Worth for editing the specification and Usenix paper David Dawes for XFree86 DDX integration work Thomas Winischhofer for the hardware-accelerated SiS rotation implementation Matthew Tippett and Kevin Martin for splitting outputs and CRTCs to more fully expose what video hardware can do ❧❧❧❧❧❧❧❧❧❧❧ 2. Screen change model Screens may change dynamically, either under control of this extension, or due to external events. Examples include: monitors being swapped, pressing a button to switch from internal display to an external monitor on a laptop, or, eventually, the hotplug of a display card entirely on busses such as Cardbus or Express Card which permit hot-swap (which will require other work in addition to this extension). Since the screen configuration is dynamic and asynchronous to the client and may change at any time RandR provides mechanisms to ensure that your clients view is up to date with the configuration possibilities of the moment and enforces applications that wish to control the configuration to prove that their information is up to date before honoring requests to change the screen configuration (by requiring a timestamp on the request). Interested applications are notified whenever the screen configuration changes, providing the current size of the screen and subpixel order (see the Render extension [RENDER]), to enable proper rendering of subpixel decimated client text to continue, along with a time stamp of the configuration change. A client must refresh its knowledge of the screen configuration before attempting to change the configuration after a notification, or the request will fail. To avoid multiplicative explosion between orientation, reflection and sizes, the sizes are only those sizes in the normal (0) rotation. Rotation and reflection and how they interact can be confusing. In Randr, the coordinate system is rotated in a counter-clockwise direction relative to the normal orientation. Reflection is along the window system coordinate system, not the physical screen X and Y axis, so that rotation and reflection do not interact. The other way to consider reflection is to is specified in the "normal" orientation, before rotation, if you find the other way confusing. We expect that most clients and toolkits will be oblivious to changes to the screen structure, as they generally use the values in the connections Display structure directly. By toolkits updating the values on the fly, we believe pop-up menus and other pop up windows will position themselves correctly in the face of screen configuration changes (the issue is ensuring that pop-ups are visible on the reconfigured screen). ❧❧❧❧❧❧❧❧❧❧❧ 3. Data Types The subpixel order is shared with the Render extension, and is documented there. The only datatype defined is the screen size, defined in the normal (0 degree) orientation. ❧❧❧❧❧❧❧❧❧❧❧ 4. Errors Errors are sent using core X error reports. Output A value for an OUTPUT argument does not name a defined OUTPUT. CRTC A value for a CRTC argument does not name a defined CRTC. Mode A value for a MODE argument does not name a defined MODE. ❧❧❧❧❧❧❧❧❧❧❧ 5. Protocol Types RRCONFIGSTATUS { Success InvalidConfigTime InvalidTime Failed } A value of type RRCONFIGSTATUS returned when manipulating the output configuration or querying information from the server that has some time-dependency. InvalidConfigTime indicates that the supplied configuration timestamp does not match the current X server configuration timestamp. Usually this means that the output configuration has changed since the timestamp was received by the application. InvalidTime indicates that the supplied output reconfiguration time is earlier than the most recent output reconfiguration request. Generally this indicates that another application has reconfigured the output using a later timestamp. Failed is returned whenever the operation is unsuccessful for some other reason. This generally indicates that the requested output configuration is unsupported by the hardware. The goal is to make these limitations expressed by the protocol, but when that isn't possible it is correct to return this error value. If, as a implentor, you find this error code required, please submit the hardware constraints that exist so that a future version of the extension can correctly capture the configuration constraints in your system. ROTATION { Rotate_0 Rotate_90 Rotate_180 Rotate_270 Reflect_X Reflect_Y } These values are used both to indicate a set of allowed rotations and reflections as well as to indicate a specific rotation and reflection combination. RRSELECTMASK { RRScreenChangeNotifyMask RRCrtcChangeNotifyMask (New in version 1.2) RROutputChangeNotifyMask (New in version 1.2) RROutputPropertyNotifyMask (New in version 1.2) } SIZEID { CARD16 } MODE { XID or None } CRTC { XID } OUTPUT { XID } CONNECTION { Connected, Disconnected, UnknownConnection } This value provides an indication of whether an output is actually connected to a monitor or other presentation device. SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render SubPixelHorizontalRGB extensions definitions; they are here SubPixelHorizontalBGR only for convenience. SubPixelVerticalRGB SubPixelVerticalBGR SubPixelNone } SCREENSIZE { widthInPixels, heightInPixels: CARD16 widthInMillimeters, heightInMillimeters: CARD16 } MODEFLAG { HSyncPositive HSyncNegative VSyncPositive VSyncNegative Interlace DoubleScan CSync CSyncPositive CSyncNegative HSkewPresent BCast PixelMultiplex DoubleClock ClockDivideBy2 } MODEINFO { id: MODE name: STRING width, height: CARD16 dotClock: CARD32 hSyncStart, hSyncEnd, hTotal, hSkew: CARD16 vSyncStart, vSyncEnd, vTotal: CARD16 modeFlags: SETofMODEFLAG } REFRESH { rates: LISTofCARD16 } ❧❧❧❧❧❧❧❧❧❧❧ 6. Extension Initialization The name of this extension is "RANDR". ┌─── RRQueryVersion client-major-version: CARD32 client-minor-version: CARD32 ▶ major-version: CARD32 minor-version: CARD32 └─── The client sends the highest supported version to the server and the server sends the highest version it supports, but no higher than the requested version. Major versions changes can introduce incompatibilities in existing functionality, minor version changes introduce only backward compatible changes. It is the clients responsibility to ensure that the server supports a version which is compatible with its expectations. ❧❧❧❧❧❧❧❧❧❧❧ 7. Extension Requests ┌─── RRSelectInput window: WINDOW enable: SETofRRSELECTMASK └─── Errors: Window, Value If 'enable' is RRScreenChangeNotifyMask, RRScreenChangeNotify events will be sent when the screen configuration changes, either from this protocol extension, or due to detected external screen configuration changes. RRScreenChangeNotify may also be sent when this request executes if the screen configuration has changed since the client connected, to avoid race conditions. New for version 1.2: If 'enable' contains RRCrtcChangeMask, RRCrtcChangeNotify events will be sent when a the configuration for a CRTC associated with the screen changes, either through this protocol extension or due to detected external changes. RRCrtcChangeNotify may also be sent when this request executes if the CRTC configuration has changed since the client connected, to avoid race conditions. If 'enable' contains RROutputChangeMask, RROutputChangeNotify events will be sent when a the configuration for an output associated with the screen changes, either through this protocol extension or due to detected external changes. RROutputChangeNotify may also be sent when this request executes if the output configuration has changed since the client connected, to avoid race conditions. If 'enable' contains RROutputPropertyNotifyMask, RROutputPropertyNotify events will be sent when properties change on this output. ┌─── RRSetScreenConfig window: WINDOW timestamp: TIMESTAMP config-timestamp: TIMESTAMP size-id: SIZEID rotation: ROTATION rate: CARD16 ▶ status: RRCONFIGSTATUS new-timestamp: TIMESTAMP config-timestamp: TIMESTAMP root: WINDOW subpixelOrder: SUBPIXELORDER └─── Errors: Value, Match If 'timestamp' is less than the time when the configuration was last successfully set, the request is ignored and InvalidTime returned in status. If 'config-timestamp' is not equal to when the server's screen configurations last changed, the request is ignored and InvalidConfigTime returned in status. This could occur if the screen changed since you last made a RRGetScreenInfo request, perhaps by a different piece of display hardware being installed. Rather than allowing an incorrect call to be executed based on stale data, the server will ignore the request. 'rate' contains the desired refresh rate. If it is zero, the server selects an appropriate rate. This request may fail for other indeterminate reasons, in which case 'status' will be set to Failed and no configuration change will be made. This request sets the screen to the specified size, rate, rotation and reflection. When this request succeeds, 'status' contains Success and the requested changes to configuration will have been made. 'new-time-stamp' contains the time at which this request was executed. 'config-timestamp' contains the time when the possible screen configurations were last changed. 'root' contains the root window for the screen indicated by the window. 'subpixelOrder' contains the resulting subpixel order of the screen to allow correct subpixel rendering. Value errors are generated when 'rotation', 'rate' or 'size-id' are invalid. ┌─── RRGetScreenInfo window: WINDOW ▶ rotations: SETofROTATION root: WINDOW timestamp: TIMESTAMP config-timestamp: TIMESTAMP size-id: SIZEID rotation: ROTATION rate: CARD16 sizes: LISTofSCREENSIZE refresh: LISTofREFRESH └─── Errors: Window RRGetScreenInfo returns information about the current and available configurations for the screen associated with 'window'. 'rotations' contains the set of rotations and reflections supported by the screen. 'root' is the root window of the screen. 'config-timestamp' indicates when the screen configuration information last changed: requests to set the screen will fail unless the timestamp indicates that the information the client is using is up to date, to ensure clients can be well behaved in the face of race conditions. 'timestamp' indicates when the configuration was last set. 'size-id' indicates which size is active. 'rate' is the current refresh rate. This is zero when the refresh rate is unknown or on devices for which refresh is not relevant. 'sizes' is the list of possible frame buffer sizes (at the normal orientation. Each size indicates both the linear physical size of the screen and the pixel size. 'refresh' is the list of refresh rates for each size. Each element of 'sizes' has a corresponding element in 'refresh'. An empty list indicates no known rates, or a device for which refresh is not relevant. The default size of the screen (the size that would become the current size when the server resets) is the first size in the list. 7.1. Extension Requests added in version 1.2 of the extension As introduced above, version 1.2 of the extension splits the screen size from the crtc and output configuration, permitting the subset of the screen presented by multiple outputs to be configured. As a separate notion, the size of the screen itself may be arbitrarily configured within a defined range. As crtcs and outputs are added and removed from the system, the set returned by the extension will change so that applications can detect dynamic changes in the display environment. ┌─── RRGetScreenSizeRange window: WINDOW ▶ CARD16 minWidth, minHeight CARD16 maxWidth, maxHeight └─── Errors: Window Returns the range of possible screen sizes. The screen may be set to any size within this range. ┌─── RRSetScreenSize window: WINDOW width: CARD16 height: CARD16 width-in-millimeters: CARD32 height-in-millimeters: CARD32 └─── Errors: Window, Match, Value Sets the screen to the specified size. 'width' and 'height' must be within the range allowed by GetScreenSizeRanges, otherwise a Value error results. All active monitors must be configured to display a subset of the specified size, else a Match error results. 'width-in-millimeters' and 'height-in-millimeters' can be set to reflect the physical size of the screen reported both through this extension and the core protocol. They must be non-zero, or Value error results. ┌─── RRGetScreenResources window: WINDOW ▶ timestamp: TIMESTAMP config-timestamp: TIMESTAMP crtcs: LISTofCRTC outputs: LISTofOUTPUT modes: LISTofMODEINFO └─── Errors: Window RRGetScreenResources returns the list of outputs and crtcs connected to the screen associated with 'window'. 'timestamp' indicates when the configuration was last set. 'config-timestamp' indicates when the configuration information last changed. Requests to configure the output will fail unless the timestamp indicates that the information the client is using is up to date, to ensure clients can be well behaved in the face of race conditions. 'crtcs' contains the list of CRTCs associated with the screen. 'outputs' contains the list of outputs associated with the screen. 'modes' contains the list of modes associated with the screen This request explicitly asks the server to ensure that the configuration data is up-to-date wrt the hardware. If that requires polling, this is when such polling would take place. Requests for further information should not poll, but rather return the data collected at this point. ┌─── RRGetOutputInfo output: OUTPUT config-timestamp: TIMESTAMP ▶ status: RRCONFIGSTATUS timestamp: TIMESTAMP crtc: CRTC name: STRING connection: CONNECTION subpixel-order: SUBPIXELORDER widthInMillimeters, heightInMillimeters: CARD32 crtcs: LISTofCRTC clones: LISTofOUTPUT modes: LISTofOUTPUT num-preferred: CARD16 └─── Errors: Output RRGetOutputInfo returns information about the current and available configurations 'output'. If 'config-timestamp' does not match the current configuration timestamp (as returned by RRGetScreenResources), 'status' is set to InvalidConfigTime and the remaining reply data is empty. Otherwise, 'status' is set to Success. 'timestamp' indicates when the configuration was last set. 'crtc' is the current source CRTC for video data, or Disabled if the output is not connected to any CRTC. 'name' is a UTF-8 encoded string designed to be presented to the user to indicate which output this is. E.g. "S-Video" or "DVI". 'connection' indicates whether the hardware was able to detect a device connected to this output. If the hardware cannot determine whether something is connected, it will set this to UnknownConnection. 'subpixel-order' contains the resulting subpixel order of the connected device to allow correct subpixel rendering. 'widthInMillimeters' and 'heightInMillimeters' report the physical size of the displayed area. If unknown, or not really fixed (e.g., for a projector), these values are both zero. 'crtcs' is the list of CRTCs that this output may be connected to. Attempting to connect this output to a different CRTC results in a Match error. 'clones' is the list of outputs which may be simultaneously connected to the same CRTC along with this output. Attempting to connect this output with an output not in the 'clones' list results in a Match error. 'modes' is the list of modes supported by this output. Attempting to connect this output to a CRTC not using one of these modes results in a Match error. The first 'num-preferred' modes in 'modes' are preferred by the monitor in some way; for fixed-pixel devices, this would generally indicate which modes match the resolution of the output device. ┌─── RRListOutputProperties output:OUTPUT ▶ atoms: LISTof ATOM └─── Errors: Output This request returns the atoms of properties currently defined on the output. ┌─── RRQueryOutputProperty output: OUTPUT property: ATOM ▶ pending: BOOL range: BOOL immutable: BOOL valid-values: LISTofINT32 └─── Errors: Name, Atom, Output If the specified property does not exist for the specified output, then a Name error is returned. If 'pending' is TRUE, changes made to property values with RRChangeOutputProperty will be saved in the pending property value and be automatically copied to the current value on the next RRSetCrtcConfig request involving the named output. If 'pending' is FALSE, changes are copied immediately. If 'range' is TRUE, then the valid-values list will contain precisely two values indicating the minimum and maximum allowed values. If 'range' is FALSE, then the valid-values list will contain the list of possible values; attempts to set other values will result in a Value error. If 'immutable' is TRUE, then the property configuration cannot be changed by clients. Immutable properties are interpreted by the X server. ┌─── RRConfigureOutputProperty output: OUTPUT property: ATOM pending: BOOL range: BOOL valid-values: LISTofINT32 └─── Errors: Access, Name, Atom, Output If the specified property is 'immutable', an Access error is returned. Otherwise, the configuration of the specified property is changed to the values provided in this request. If the specified property does not exist for the specified output, it is created with an empty value and None type. ┌─── RRChangeOutputProperty output: OUTPUT property, type: ATOM format: {8, 16, 32} mode: { Replace, Prepend, Append } data: LISTofINT8 or LISTofINT16 or LISTofINT32 └─── Errors: Alloc, Atom, Match, Value, Output This request alters the value of the property for the specified output. If the property is marked as a 'pending' property, only the pending value of the property is changed. Otherwise, changes are reflected in both the pending and current values of the property. The type is uninterpreted by the server. The format specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities so that the server can correctly byte-swap as necessary. If the mode is Replace, the previous property value is discarded. If the mode is Prepend or Append, then the type and format must match the existing property value (or a Match error results). If the property is undefined, it is treated as defined with the correct type and format with zero-length data. For Prepend, the data is tacked on to the beginning of the existing data, and for Append, it is tacked on to the end of the existing data. This request generates a OutputPropertyNotify The lifetime of a property is not tied to the storing client. Properties remain until explicitly deleted, until the output is destroyed, or until server reset (see section 10). The maximum size of a property is server-dependent and may vary dynamically. ┌─── RRDeleteOutputProperty output: OUTPUT property: ATOM └─── Errors: Atom, Output This request deletes the property from the specified window if the property exists and generates a OutputPropertyNotify event unless the property does not exist. ┌─── RRGetOutputProperty output: OUTPUT property: ATOM type: ATOM or AnyPropertyType long-offset, long-length: CARD32 delete: BOOL pending: BOOL ▶ type: ATOM or None format: {0, 8, 16, 32} bytes-after: CARD32 value: LISTofINT8 or LISTofINT16 or LISTofINT32 └─── Errors: Atom, Value, Output If the specified property does not exist for the specified output, then the return type is None, the format and bytes-after are zero, and the value is empty. The delete argument is ignored in this case. If the specified property exists but its type does not match the specified type, then the return type is the actual type of the property, the format is the actual format of the property (never zero), the bytes-after is the length of the property in bytes (even if the format is 16 or 32), and the value is empty. The delete argument is ignored in this case. If the specified property exists and either AnyPropertyType is specified or the specified type matches the actual type of the property, then the return type is the actual type of the property, the format is the actual format of the property (never zero), and the bytes-after and value are as follows, given: N = actual length of the stored property in bytes (even if the format is 16 or 32) I = 4 × offset T = N - I L = MINIMUM(T, 4 × long-length) A = N - (I + L) If 'pending' is true, and if the property holds a pending value, then the value returned will be the pending value of the property rather than the current value. The returned value starts at byte index I in the property (indexing from 0), and its length in bytes is L. However, it is a Value error if long-offset is given such that L is negative. The value of bytes-after is A, giving the number of trailing unread bytes in the stored property. If delete is True and the bytes-after is zero, the property is also deleted from the output, and a RROutputPropertyNotify event is generated. ┌─── RRCreateMode window: WINDOW modeinfo: MODEINFO ▶ mode: MODE └─── Errors: Window, Name, Value 'modeinfo' provides a new mode for outputs on the screen associated with 'window'. If the name of 'modeinfo' names an existing mode, a Name error is returned. If some parameter of the mode is not valid in some other way, a Value error is returned. The returned 'mode' provides the id for the mode. ┌─── RRDestroyMode mode: MODE └─── Errors: Mode, Access The user-defined 'mode' is destroyed. 'mode' must name a mode defined with RRCreateMode, else an Match error is returned. If 'mode' is in use by some CRTC or Output, then an Access error is returned. ┌─── RRAddOutputMode output: OUTPUT mode: MODE └─── Errors: Output, Mode, Match 'output' indicates which output is to be configured. 'mode' specifies which mode to add. If 'mode' is not valid for 'output', then a Match error is generated. This request generates OutputChangeNotify events. ┌─── RRDeleteOutputMode output: OUTPUT mode: MODE └─── Errors: Output, Mode 'output' indicates which output is to be configured. 'mode' specifies which mode to delete. 'mode' must have been added with RRAddOutputMode, else an Access error is returned. 'mode' must not be active, else a Match error is returned. This request generates OutputChangeNotify events. ┌─── RRGetCrtcInfo crtc: CRTC config-timestamp: TIMESTAMP ▶ status: RRCONFIGSTATUS timestamp: TIMESTAMP x, y: INT16 width, height: CARD16 mode: MODE rotation: ROTATION outputs: LISTofOUTPUT rotations: SETofROTATION possible-outputs: LISTofOUTPUT └─── Errors: Window RRGetCrtcModes returns information about the current and available configurations for the specified crtc connected to the screen associated with 'window'. If 'config-timestamp' does not match the current configuration timestamp (as returned by RRGetScreenResources), 'status' is set to InvalidConfigTime and the remaining reply data is empty. Otherwise, 'status' is set to Success. 'timestamp' indicates when the configuration was last set. 'x' and 'y' indicate the position of this CRTC within the screen region. They will be set to 0 when the CRTC is disabled. 'width' and 'height' indicate the size of the area presented by this CRTC. 'mode' indicates which mode is active, or None indicating that the CRTC has been disabled and is not displaying the screen contents. 'rotation' indicates the active rotation. It is set to Rotate_0 when the CRTC is disabled. 'outputs' is the list of outputs currently connected to this CRTC and is empty when the CRTC is disabled. 'rotations' contains the set of rotations and reflections supported by the CRTC. 'possible-outputs' lists all of the outputs which may be connected to this CRTC. ┌─── RRSetCrtcConfig crtc: CRTC timestamp: TIMESTAMP config-timestamp: TIMESTAMP x, y: INT16 mode: MODE rotation: ROTATION outputs: LISTofOUTPUT ▶ status: RRCONFIGSTATUS new-timestamp: TIMESTAMP └─── Errors: Value, Match If 'timestamp' is less than the time when the configuration was last successfully set, the request is ignored and InvalidTime returned in status. If 'config-timestamp' is not equal to when the monitor's configuration last changed, the request is ignored and InvalidConfigTime returned in status. This could occur if the monitor changed since you last made a RRGetScreenInfo request, perhaps by a different monitor being connected to the machine. Rather than allowing an incorrect call to be executed based on stale data, the server will ignore the request. 'x' and 'y' contain the desired location within the screen for this monitor's content. 'x' and 'y' must be within the screen size, else a Value error results. 'mode' is either the desired mode or None indicating the CRTC should be disabled. If 'mode' is not one of these values, a Value error results. 'mode' must be valid for all of the configured outputs, else a Match error. 'rotation' contains the desired rotation along with which reflections should be enabled. The rotation and reflection values must be among those allowed for this monitor, else a Value error results. 'outputs' contains the set of outputs that this CRTC should be connected to. The set must be among the list of acceptable output sets for this CRTC or a Match error results. If 'mode' is None, then 'outputs' must be empty, else a Match error results. Conversely, if 'mode' is not None, then 'outputs' must not be empty, else a Match error results. This request may fail for other indeterminate reasons, in which case 'status' will be set to Failed and no configuration change will be made. This request sets the CRTC to the specified position, mode, rotation and reflection. The entire area of the CRTC must fit within the screen size, else a Match error results. As an example, rotating the screen so that a single CRTC fills the entire screen before and after may necessitate disabling the CRTC, resizing the screen, then re-enabling the CRTC at the new configuration to avoid an invalid intermediate configuration. When this request succeeds, 'status' contains Success and the requested changes to configuration will have been made. 'new-time-stamp' contains the time at which this request was executed. ┌─── RRGetCrtcGammaSize crtc: CRTC ▶ size: CARD16 └─── Errors: Crtc This request returns the size of the gamma ramps used by 'crtc'. ┌─── RRGetCrtcGamma crtc: CRTC ▶ red: LISTofCARD16 green: LISTofCARD16 blue: LISTofCARD16 └─── Errors: Crtc This request returns the currently set gamma ramps for 'crtc'. All three lists will be the size returned by the RRGetCrtcGammaSize request. ┌─── RRSetCrtcGamma crtc: CRTC red: LISTofCARD16 green: LISTofCARD16 blue: LISTofCARD16 └─── Errors: Crtc, Match This request sets the gamma ramps for 'crtc'. All three lists must be the size returned by RRGetCrtcGammaSize else a Value error results. ❧❧❧❧❧❧❧❧❧❧❧ 8. Extension Events Clients MAY select for ConfigureNotify on the root window to be informed of screen changes. This may be advantageous if all your client needs to know is the size of the root window, as it avoids round trips to set up the extension. RRScreenChangeNotify is sent if RRSelectInput has requested it whenever properties of the screen change, which may be due to external factors, such as re-cabling a monitor, etc. ┌─── RRScreenChangeNotify rotation: ROTATION; new rotation sequenceNumber: CARD16 low 16 bits of request seq. number timestamp: TIMESTAMP time screen was changed configTimestamp: TIMESTAMP time config data was changed root: WINDOW root window of screen window: WINDOW window requesting notification size-id: SIZEID index of new size subpixelOrder: SUBPIXELORDER order of subpixels widthInPixels: CARD16 heightInPixels: CARD16 widthInMillimeters: CARD16 heightInMillimeters: CARD16 └─── This event is generated whenever the screen configuration is changed and sent to requesting clients. 'timestamp' indicates when the screen configuration was changed. 'configTimestamp' says when the last time the configuration was changed. 'root' is the root of the screen the change occurred on, 'window' is window selecting for this event. 'size-id' contains the index of the current size. This event is sent whenever the screen's configuration changes or if a new screen configuration becomes available that was not available in the past. In this case (config-timestamp in the event not being equal to the config-timestamp returned in the last call to RRGetScreenInfo), the client MUST call RRGetScreenInfo to update its view of possible screen configurations to have a correct view of possible screen organizations. Clients which select screen change notification events may be sent an event immediately if the screen configuration was changed between when they connected to the X server and selected for notification. This is to prevent a common race that might occur on log-in, where many applications start up just at the time when a display manager or log in script might be changing the screen size or configuration. 8.1 Events added in version 1.2 of the RandR extension ┌─── RROutputChangeNotify: timestamp: TIMESTAMP time screen was reconfigured config-timestamp: TIMESTAMP time available config data was changed window: WINDOW window requesting notification output: OUTPUT output affected by change crtc: CRTC connected CRTC or None mode: MODE mode in use on CRTC or None connection: CONNECTION connection status └─── This event is generated whenever the available output configurations have changed and is sent to requesting clients. 'timestamp' indicates when the crtc configuration was changed by a client. 'config-timestamp' says when the last time the available configurations changed. 'root' is the root of the screen the change occurred on, 'window' is window selecting for this event. The precise change can be detected by examining the new state of the system. ┌─── RROutputPropertyNotify: window: WINDOW window requesting notification output: OUTPUT output affected by change atom: ATOM affected property time: TIMESTAMP time property was changed subpixel-order: SUBPIXELORDER order of subpixels state: { NewValue, Deleted } new property state └─── This event is reported to clients selecting RROutputPropertyChange on the window and is generated with state NewValue when a property of the window is changed using RRChangeOutputProperty even when adding zero-length data and when replacing all or part of a property with identical data. It is generated with state Deleted when a property of the window is deleted using either RRDeleteOutputProperty or RRGetOutputProperty. The timestamp indicates the server time when the property was changed. ┌─── RRCrtcChangeNotify timestamp: TIMESTAMP time monitor was changed config-timestamp: TIMESTAMP time config data was changed root: WINDOW root window of screen window: WINDOW window requesting notification crtc: CRTC CRTC which changed mode: MODE new mode rotation: ROTATION; new rotation x: INT16 x position of CRTC within screen y: INT16 y position of CRTC within screen └─── This event is generated whenever the CRTC configuration is changed and sent to requesting clients. 'timestamp' indicates when the CRTC configuration was changed. 'config-timestamp' says when the last time the configuration was changed. 'root' is the root of the screen the change occurred on, 'window' is window selecting for this event. This event is sent whenever the monitor's configuration changes or if a new monitor configuration becomes available that was not available in the past. In this case (config-timestamp in the event not being equal to the config-timestamp returned in the last call to RRGetCrtcModes), the client MUST call RRGetCrtcModes to update its view of possible monitor configurations to have a correct view of possible monitor organizations. Clients which select monitor change notification events may be sent an event immediately if the monitor configuration was changed between when they connected to the X server and selected for notification. This is to prevent a common race that might occur on log-in, where many applications start up just at the time when a display manager or log in script might be changing the monitor size or configuration. ❧❧❧❧❧❧❧❧❧❧❧ 9. Extension Versioning The RandR extension was developed in parallel with the implementation to ensure the feasibility of various portions of the design. As portions of the extension are implemented, the version number of the extension has changed to reflect the portions of the standard provided. This document describes the version 1.2 of the specification, the partial implementations have version numbers less than that. Here's a list of what each version provided: 0.0: This prototype implemented resize and rotation in the TinyX server Used approximately the protocol described in the Usenix paper. Appeared in the TinyX server in XFree86 4.2, but not in the XFree86 main server. 0.1: Added subpixel order, added an event for subpixel order. This version was never checked in to XFree86 CVS. 1.0: Implements resize, rotation, and reflection. Implemented both in the XFree86 main server (size change only at this date), and fully (size change, rotation, and reflection) in XFree86's TinyX server. 1.1: Added refresh rates 1.2: Separate screens from CRTCs and outputs, switch to full VESA modes Compatibility between 0.0 and 1.0 was *NOT* preserved, and 0.0 clients will fail against 1.0 servers. The wire encoding op-codes were changed for GetScreenInfo to ensure this failure in a relatively graceful way. Version 1.1 servers and clients are cross compatible with 1.0. Version 1.1 is considered to be stable and we intend upward compatibility from this point. Version 1.2 offers an extended model of the system with multiple output support. It offers backward compatibility with version 1.1. ❧❧❧❧❧❧❧❧❧❧❧ 10. Relationship with other extensions Two other extensions have a direct relationship with this extension. This section attempts to explain how these three are supposed to work together. 10.1 XFree86-VidModeExtension XFree86-VidModeExtension changes the configuration of a single monitor attached to the screen without changing the configuration of the screen itself. It provides the ability to specify new mode lines for the server to use along with selecting among existing mode lines. As it uses screen numbers instead of window identifiers, it can be used to affect multiple monitors in a single-screen Xinerama configuration. However, the association between screen numbers and root windows in a multi-Screen environment is not defined by the extension. Version 2.0 of this extension added the ability to adjust the DAC values in a TrueColor server to modify the brightness curves of the display. All of the utility of this extension is subsumed by RandR version 1.2, RandR should be used in preference to XFree86-VidModeExtension where both are present. 10.2 Xinerama Xinerama provides a mechanism for describing the relationship between the overall screen display and monitors placed within that area. As such, it provides the query functionality of RandR 1.2 without any of the configuration functionality. Applications using Xinerama to discover monitor geometry can continue to do so, with the caveat that they will not be informed of changes when they occur. However, Xinerama configuration data will be updated, so applications selecting for RandR notification and re-querying the configuration with the Xinerama extension will get updated information. It is probably better to view RandR as a superset of Xinerama at this point and use it in preference to Xinerama where both are present. ❧❧❧❧❧❧❧❧❧❧❧ Appendix A. Protocol Encoding Syntactic Conventions This document uses the same syntactic conventions as the core X protocol encoding document. A.1 Common Types ┌─── ROTATION 0x0001 Rotate_0 0x0002 Rotate_90 0x0004 Rotate_180 0x0008 Rotate_270 0x0010 Reflect_X 0x0020 Reflect_Y └─── Used to encode both sets of possible rotations and individual selected rotations. ┌─── RRSELECTMASK 0x0001 ScreenChangeNotifyMask 0x0002 CrtcChangeNotifyMask Added in version 1.2 0x0004 OutputChangeNotifyMask Added in version 1.2 0x0008 OutputPropertyNotifyMask Added in version 1.2 └─── Event select mask for RRSelectInput ┌─── RRCONFIGSTATUS 0x0 Success 0x1 InvalidConfigTime 0x2 InvalidTime 0x3 Failed └─── Return status for requests which depend on time. ┌─── MODEINFO (32) Added in version 1.2 4 CARD32 id 2 CARD16 width in pixels 2 CARD16 height in pixels 4 CARD32 dot clock 2 CARD16 h sync start 2 CARD16 h sync end 2 CARD16 h total 2 CARD16 h skew 2 CARD16 v sync start 2 CARD16 v sync end 2 CARD16 v total 2 CARD16 name length 4 SETofMODEFLAG mode flags └─── An output mode specifies the complete CRTC timings for a specific mode. The vertical and horizontal synchronization rates can be computed given the dot clock and the h total/v total values. If the dot clock is zero, then all of the timing parameters and flags are not used, and must be zero as this indicates that the timings are unknown or otherwise unused. The name itself will be encoded separately in each usage. ┌─── MODEFLAG 0x00000001 HSyncPositive 0x00000002 HSyncNegative 0x00000004 VSyncPositive 0x00000008 VSyncNegative 0x00000010 Interlace 0x00000020 DoubleScan 0x00000040 CSync 0x00000080 CSyncPositive 0x00000100 CSyncNegative 0x00000200 HSkewPresent 0x00000400 BCast 0x00000800 PixelMultiplex 0x00001000 DoubleClock 0x00002000 ClockDivideBy2 └─── ┌─── CONNECTION 0 Connected 1 Disconnected 2 UnknownConnection └─── A.2 Protocol Requests Opcodes 1 and 3 were used in the 0.0 protocols, and will return errors if used in version 1.0. ┌─── RRQueryVersion 1 CARD8 major opcode 1 0 RandR opcode 2 3 length 4 CARD32 major version 4 CARD32 minor version ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 1 CARD32 major version 1 CARD32 minor version └─── ┌─── RRSetScreenConfig 1 CARD8 major opcode 1 2 RandR opcode 2 6 length 4 WINDOW window on screen to be configured 4 TIMESTAMP timestamp 4 TIMESTAMP config timestamp 2 SIZEID size index 2 ROTATION rotation/reflection 2 CARD16 refresh rate (1.1 only) 2 CARD16 pad ▶ 1 1 Reply 1 RRCONFIGSTATUS status 2 CARD16 sequence number 4 0 reply length 4 TIMESTAMP new timestamp 4 TIMESTAMP new configuration timestamp 4 WINDOW root 2 SUBPIXELORDER subpixel order defined in Render 2 CARD16 pad4 4 CARD32 pad5 4 CARD32 pad6 └─── ┌─── RRSelectInput 1 CARD8 major opcode 1 4 RandR opcode 2 3 length 4 WINDOW window 2 SETofRRSELECTMASK enable 2 CARD16 pad └─── ┌─── RRGetScreenInfo 1 CARD8 major opcode 1 5 RandR opcode 2 2 length 4 WINDOW window ▶ 1 1 Reply 1 CARD8 set of Rotations 2 CARD16 sequence number 4 0 reply length 4 WINDOW root window 4 TIMESTAMP timestamp 4 TIMESTAMP config timestamp 2 CARD16 number of SCREENSIZE following 2 SIZEID current size index 2 ROTATION current rotation and reflection 2 CARD16 current rate (added in version 1.1) 2 CARD16 length of rate info (number of CARD16s) 2 CARD16 pad SCREENSIZE 2 CARD16 width in pixels 2 CARD16 height in pixels 2 CARD16 width in millimeters 2 CARD16 height in millimeters REFRESH 2 CARD16 number of rates (n) 2n CARD16 rates └─── A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetScreenSizeRange 1 CARD8 major opcode 1 6 RandR opcode 2 2 length 4 WINDOW window ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 2 CARD16 minWidth 2 CARD16 minHeight 2 CARD16 maxWidth 2 CARD16 maxHeight 16 unused └─── ┌─── RRSetScreenSize 1 CARD8 major opcode 1 7 RandR opcode 2 5 length 4 WINDOW window 2 CARD16 width 2 CARD16 height 4 CARD32 width in millimeters 4 CARD32 height in millimeters └─── ┌─── RRGetScreenResources 1 CARD8 major opcode 1 8 RandR opcode 2 2 length 4 WINDOW window ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 c+o+8m+(b+p)/4 reply length 4 TIMESTAMP timestamp 4 TIMESTAMP config-timestamp 2 c number of CRTCs 2 o number of outputs 2 m number of modeinfos 2 b total bytes in mode names 8 unused 4c LISTofCRTC crtcs 4o LISTofOUTPUT outputs 32m LISTofMODEINFO modeinfos b STRING8 mode names p unused, p=pad(b) └─── ┌─── RRGetOutputInfo 1 CARD8 major opcode 1 9 RandR opcode 2 3 length 4 OUTPUT output 4 TIMESTAMP config-timestamp ▶ 1 1 Reply 1 RRCONFIGSTATUS status 2 CARD16 sequence number 4 1+c+m+(n+p)/4 reply length 4 TIMESTAMP timestamp 4 CRTC current connected crtc 4 CARD32 width in millimeters 4 CARD32 height in millimeters 1 CONNECTION connection 1 SUBPIXELORDER subpixel-order 2 c number of CRTCs 2 m number of modes 2 p number of preferred modes 2 o number of clones 2 n length of name 4c LISTofCRTC crtcs 4m LISTofMODE modes n STRING8 name p unused, p=pad(n) └─── ┌─── RRListOutputProperties 1 CARD8 major opcode 1 10 RandR opcode 2 2 length 4 OUTPUT output ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 n reply length 2 n number of ATOMs in atoms 22 unused 4n LISTofATOM atoms └─── ┌─── RRQueryOutputProperty 1 CARD8 major opcode 1 11 RandR opcode 2 3 request length 4 OUTPUT output 4 ATOM property ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 n reply length 1 BOOL pending 1 BOOL range 1 BOOL immutable 21 unused 4n LISTofINT32 valid values └─── ┌─── RRConfigureOutputProperty 1 CARD8 major opcode 1 12 RandR opcode 2 4+n request length 4 OUTPUT output 4 ATOM property 1 BOOL pending 1 BOOL range 2 unused 4n LISTofINT32 valid values └─── ┌─── RRChangeOutputProperty 1 CARD8 major opcode 1 13 RandR opcode 2 6+(n+p)/4 request length 4 OUTPUT output 4 ATOM property 4 ATOM type 1 CARD8 format 1 mode 0 Replace 1 Prepend 2 Append 2 unused 4 CARD32 length of data in format units (= n for format = 8) (= n/2 for format = 16) (= n/4 for format = 32) n LISTofBYTE data (n is a multiple of 2 for format = 16) (n is a multiple of 4 for format = 32) p unused, p=pad(n) └─── ┌─── RRDeleteOutputProperty 1 CARD8 major opcode 1 14 RandR opcode 2 3 request length 4 OUTPUT output 4 ATOM property └─── ┌─── RRGetOutputProperty 1 CARD8 major opcode 1 15 RandR opcode 2 7 request length 4 OUTPUT output 4 ATOM property 4 ATOM type 0 AnyPropertyType 4 CARD32 long-offset 4 CARD32 long-length 1 BOOL delete 1 BOOL pending 2 unused ▶ 1 1 Reply 1 CARD8 format 2 CARD16 sequence number 4 (n+p)/4 reply length 4 ATOM type 0 None 4 CARD32 bytes-after 4 CARD32 length of value in format units (= 0 for format = 0) (= n for format = 8) (= n/2 for format = 16) (= n/4 for format = 32) 12 unused n LISTofBYTE value (n is zero for format = 0) (n is a multiple of 2 for format = 16) (n is a multiple of 4 for format = 32) p unused, p=pad(n) └─── ┌─── RRCreateMode 1 CARD8 major opcode 1 16 RandR opcode 2 12+(n+p)/4 length 4 WINDOW window 32 MODEINFO mode n STRING8 mode name p unused, p=pad(n) ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 4 MODE mode 20 unused └─── ┌─── RRDestroyMode 1 CARD8 major opcode 1 17 RandR opcode 2 2 length 4 MODE mode └─── ┌─── RRAddOutputMode 1 CARD8 major opcode 1 18 RandR opcode 2 3 length 4 OUTPUT output 4 MODE mode └─── ┌─── RRDeleteOutputMode 1 CARD8 major opcode 1 19 RandR opcode 2 3 length 4 OUTPUT output 4 MODE mode └─── ┌─── RRGetCrtcInfo 1 CARD8 major opcode 1 20 RandR opcode 2 3 length 4 CRTC crtc 4 TIMESTAMP config-timestamp ▶ 1 1 Reply 1 RRCONFIGSTATUS status 2 CARD16 sequence number 4 o+p reply length 4 TIMESTATMP timestamp 2 INT16 x 2 INT16 y 2 CARD16 width 2 CARD16 height 4 MODE mode 2 ROTATION current rotation and reflection 2 ROTATION set of possible rotations 2 o number of outputs 2 p number of possible outputs 4o LISTofOUTPUT outputs 4p LISTofOUTPUT possible outputs └─── ┌─── RRSetCrtcConfig 1 CARD8 major opcode 1 21 RandR opcode 2 7+2n length 4 CRTC crtc 4 TIMESTAMP timestamp 4 TIMESTAMP config timestamp 2 INT16 x 2 INT16 y 4 MODE mode 2 ROTATION rotation/reflection 2 unused 8n LISTofOUTPUT outputs ▶ 1 1 Reply 1 RRCONFIGSTATUS status 2 CARD16 sequence number 4 0 reply length 4 TIMESTAMP new timestamp 20 unused └─── ┌─── RRGetCrtcGammaSize 1 CARD8 major opcode 1 22 RandR opcode 2 2 length 4 CRTC crtc ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 2 CARD16 size 22 unused └─── ┌─── RRGetCrtcGamma 1 CARD8 major opcode 1 23 RandR opcode 2 2 length 4 CRTC crtc ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 (6n+2)/4 reply length 2 n size 20 unused 2n LISTofCARD16 red 2n LISTofCARD16 green 2n LISTofCARD16 blue p unused, p=pad(6n) └─── ┌─── RRSetCrtcGamma 1 CARD8 major opcode 1 24 RandR opcode 2 3+(6n+2)/4 length 4 CRTC crtc 2 n size 2 unused 2n LISTofCARD16 red 2n LISTofCARD16 green 2n LISTofCARD16 blue p unused, p=pad(6n) └─── A.3 Protocol Events ┌─── RRScreenChangeNotify 1 Base + 0 code 1 ROTATION new rotation and reflection 2 CARD16 sequence number 4 TIMESTAMP timestamp 4 TIMESTAMP configuration timestamp 4 WINDOW root window 4 WINDOW request window 2 SIZEID size ID 2 SUBPIXELORDER subpixel order defined in Render 2 CARD16 width in pixels 2 CARD16 height in pixels 2 CARD16 width in millimeters 2 CARD16 height in millimeters └─── A.3.1 Protocol Events added with version 1.2 ┌─── RRCrtcChangeNotify 1 Base + 1 code 1 0 sub-code 2 CARD16 sequence number 4 TIMESTAMP timestamp 4 WINDOW request window 4 CRTC crtc affected 4 MODE mode in use 2 ROTATION new rotation and reflection 2 unused 2 INT16 x 2 INT16 y 2 CARD16 width 2 CARD16 height └─── ┌─── RROutputChangeNotify 1 Base + 1 code 1 1 sub-code 2 CARD16 sequence number 4 TIMESTAMP timestamp 4 TIMESTAMP configuration timestamp 4 WINDOW request window 4 OUTPUT output affected 4 CRTC crtc in use 4 MODE mode in use 2 ROTATION rotation in use 1 CONNECTION connection status 1 SUBPIXELORDER subpixel order └─── ┌─── RROutputPropertyNotify 1 Base + 1 code 1 2 sub-code 2 CARD16 sequence number 4 WINDOW window 4 OUTPUT output 4 ATOM atom 4 TIMESTAMP time 1 state 0 NewValue 1 Deleted 11 unused └─── A.4 Protocol Errors ┌─── ERRORS Base + 0 Output Base + 1 Crtc Base + 2 Mode └─── Bibliography [RANDR] Gettys, Jim and Keith Packard, "The X Resize and Rotate Extension - RandR", Proceedings of the 2001 USENIX Annual Technical Conference, Boston, MA [RENDER] Packard, Keith, "The X Rendering Extension", work in progress, documents found in xc/specs/Render.