From d606ad207ccef5c050374b535acb0bd3ed3b95aa Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Mon, 26 Jun 2006 12:42:50 +0200 Subject: move protocol.txt to randrproto.txt. Start updating headers for version 1.2 --- Makefile.am | 2 +- protocol.txt | 919 -------------------------------------------------- randr.h | 43 ++- randrproto.h | 1 + randrproto.txt | 1023 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 1065 insertions(+), 923 deletions(-) delete mode 100644 protocol.txt create mode 100644 randrproto.txt diff --git a/Makefile.am b/Makefile.am index 62a5502..e741694 100644 --- a/Makefile.am +++ b/Makefile.am @@ -6,4 +6,4 @@ randr_HEADERS = \ pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = randrproto.pc -EXTRA_DIST = autogen.sh randrproto.pc.in +EXTRA_DIST = autogen.sh randrproto.pc.in randrproto.txt diff --git a/protocol.txt b/protocol.txt deleted file mode 100644 index ff07f62..0000000 --- a/protocol.txt +++ /dev/null @@ -1,919 +0,0 @@ - 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: - o Modern toolkits (in this case, GTK+ 2.x) have progressed to the point - of implementing migration between screens of arbitrary depths - o 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 - o The continued decline of legacy toolkits whose design would have - required depth switching to support migration - o The lack of depth switchin 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 implementated 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, -the size of the 'porthole' shown by each monitor is independent of the -overall size of the screen, and the porthole may be located anywhere within -the screen. - -The effect is to decouple the reported size of the screen from the size -presented by each monitor, and to permit multiple monitors to present -information for a single screen. - -To extend RandR for this model, we separate out the monitor 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) monitor. - -Additional requests and events are provided for this new functionality. - -2. Acknowlegements - -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 - -2. Screen change model - -Screens may change dynamically, either under control of this -extension, or due to external events. Examples include: monitors being -swapped, you 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 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 enabel 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 stucture, 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 - -There are no new error types defined by this extension. - -5. Protocol Types - -RRCONFIGSTATUS { - Success - InvalidConfigTime - InvalidTime - Failed } -ROTATION { - Rotate_0 - Rotate_90 - Rotate_180 - Rotate_270 - Reflect_X - Reflect_Y } - -RRSELECTMASK { RRScreenChangeNotifyMask - RRMonitorChangeNotifyMask (New in version 1.2) } - -SIZEID { CARD16 or Disabled } - -MONITOR { CARD16 } - -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 } - -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 RRMonitorChangeMask, - RRMonitorChangeNotify events will be sent when a the configuration - for a monitor associated with the screen changes, either through - this protocol extension or due to detected external monitor changes. - RRMonitorChangeNotify may also be sent when this request executes if - the monitor configuration has changed since the client connected, to - avoid race conditions. - -RRSetScreenConfig - drawable: DRAWABLE - 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 - drawable. - - '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 - - where: - - 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 cooresponding 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 monitor configuration, permitting the subset of the screen -presented by multiple monitors to be configured. As a separate notion, the -size of the screen itself may be arbitrarily configured within a defined -range. - -RRGetScreenSizeRange - drawable: DRAWABLE - - -> - - CARD16 minWidth, minHeight - CARD16 maxWidth, maxHeight - - Errors: Drawable - - Returns the range of possible screen sizes. The screen may be set to - any size within this range. - -RRSetScreenSize - drawable: DRAWABLE - width: CARD16 - height: CARD16 - - Errors: Drawable, 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. - -RRGetMonitorInfo - drawable: DRAWABLE - - -> - - root: WINDOW - monitors: LISTofMONITORINFO - - where: - - MONITORINFO { - timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - x, y: INT16 - size-id: SIZEID or Disabled - rotation: ROTATION - rate: CARD16 - rotations: SETofROTATION - default-size-id: SIZEID or Disabled - sizes: LISTofSCREENSIZE - refresh: LISTofREFRESH - } - - Errors: Drawable - - RRGetMonitorInfo returns information about the current and available - configurations for all monitors connected to the screen associated - with 'window'. - - 'root' is the root window of the screen. - - 'timestamp' indicates when the configuration was last set. - - '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. - - 'x' and 'y' indicate the position of this monitor within the screen - region. They will be set to 0 when the monitor is disabled. - - 'size-id' indicates which size is active, or 'Disabled' indicating - that the monitor has been disabled and is not displaying the screen - contents. - - 'rotation' indicates the active rotation. It is set to Rotate_0 - when the monitor is disabled. - - 'rate' is the current refresh rate. This is zero when monitor is - disabled, when the refresh rate is unknown or on devices for which - refresh is not relevant. - - 'rotations' contains the set of rotations and reflections supported - by the monitor. - - 'default-size-id' is the size the monitor is set to at server - reset time. - - 'sizes' is the list of possible displayed sizes (with rotation set - to Rotate_0). Each size indicates both the linear physical size of - the monitor and the pixel size of the displayed area. - - 'refresh' is the list of refresh rates for each size. Each element - of 'sizes' has a cooresponding element in 'refresh'. An empty list - indicates no known rates, or a device for which refresh is not - relevant. - -RRSetMonitorConfig - drawable: DRAWABLE - monitor-index: MONITOR - timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - x, y: INT16 - size-id: SIZEID - rotation: ROTATION - rate: CARD16 - - -> - - status: RRCONFIGSTATUS - new-timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - root: WINDOW - monitor: MONITOR - 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 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. - - 'size-id' contains the index of desired size or Disabled - indicating the monitor should be disabled. 'size-id' must be - either a valid size index or 'Disabled', else a Value error results. - - '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. - - 'rate' contains the desired refresh rate. If it is zero, the server - selects an appropriate rate. Otherwise, the rate must be valid for - the selected size, else a Value 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 monitor to the specified position size, rate, - rotation and reflection. The entire area of the monitor must fit - within the screen size, else a Match error results. As an example, - rotating the screen so that a single monitor fills the entire screen - before and after may necessitate disabling the monitor, resizing the - screen, then re-enabling the monitor 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. - - 'config-timestamp' contains the time when the possible screen - configurations were last changed. - - 'root' contains the root window for the screen indicated by the - drawable. - - 'subpixelOrder' contains the resulting subpixel order of the monitor - to allow correct subpixel rendering. - -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 -clients need 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 recabling a monitor, etc. - -RRScreenChangeNotify - - rotation: ROTATION; new rotation - sequenceNumber: CARD16 low 16 bits of request's 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 - -RRMonitorChangeNotify - - rotation: ROTATION; new rotation - sequenceNumber: CARD16 low 16 bits of request's seq. number - timestamp: TIMESTAMP time monitor was changed - configTimestamp: TIMESTAMP time config data was changed - root: WINDOW root window of screen - window: WINDOW window requesting notification - monitor-index: MONITOR monitor which changed - size-id: SIZEID new size index - subpixelOrder: SUBPIXELORDER order of subpixels - x: INT16 x position of monitor within screen - y: INT16 y position of monitor within screen - - This event is generated whenever the monitor configuration is changed - and sent to requesting clients. 'timestamp' indicates when the - monitor 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 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 RRGetMonitorInfo), the client MUST call - RRGetMonitorInfo 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 provied. -This document describes the version 1.0 of the specification, the -partial implementations have version numbers less than that. Here's a -list of what each version before 1.0 implemented: - - 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 out screens from monitors - -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. - -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. - -Most of the utility of this extension is subsumed by RandR version 1.2, with -the noted exception of specifying new mode lines and the gamma adjustments. -If these features continue to be useful, either some relationship between -the screen indices used in the XFree86-VidModeExtension and the -screen/monitor pairs used int RandR or an incorporation of this -functionality into RandR might be needed. - -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. - -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 - - - RRSELECTMASK - - 0x0001 ScreenChangeNotifyMask - 0x0002 MonitorChangeNotifyMask Added in version 1.2 - - RRCONFIGSTATUS - - 0x0 Success - 0x1 InvalidConfigTime - 0x2 InvalidTime - 0x3 Failed - - SIZEID - 0xffff Disabled - -A.2 Protocol Requests - - -Opcodes 0x1 and 0x3 were used in the 0.0 protocols, and will return -errors if used in version 1.0. - - RRQueryVersion - - 1 CARD8 major opcode - 1 0x01 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 0x02 RandR opcode - 2 6 length - 4 DRAWABLE drawable 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 0x04 RandR opcode - 2 3 length - 4 WINDOW window - 2 SETofRRSELECTMASK enable - 2 CARD16 pad - - - RRGetScreenInfo - - 1 CARD8 major opcode - 1 0x05 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 0x06 RandR opcode - 2 2 length - 4 DRAWABLE drawable - -> - 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 - 4 unused - 4 unused - 4 unused - 4 unused - - - RRSetScreenSize - - 1 CARD8 major opcode - 1 0x07 RandR opcode - 2 3 length - 4 DRAWABLE drawable - 2 CARD16 width - 2 CARD16 height - - - RRGetMonitorInfo - - 1 CARD8 major opcode - 1 0x08 RandR opcode - 2 2 length - 4 DRAWABLE drawable - -> - 1 1 Reply - 1 unused - 2 CARD16 sequence number - 4 m*7 + s*2 + (r*2+p)/4 reply length - 4 WINDOW root - 2 CARD16 m = number of MONITORINFO following - 2 CARD16 s = number of SIZE following - 2 CARD16 r = number of CARD16 in rates following - 14 unused - m*28 LISTofMONITORINFO one per monitor - s*8 LISTofSCREENSIZE for all monitors - r*2 LISTofREFRESH refresh rates - p pad pad(r*2) - - MONITORINFO - 4 TIMESTAMP timestamp - 4 TIMESTAMP config-timestamp - 2 INT16 x - 2 INT16 y - 2 ROTATION rotation - 2 CARD16 rate - 2 SETofROTATION rotations - 2 SIZEID or Disabled default-size-id - 2 CARD16 start offset in LISTofSCREENSIZE - 2 CARD16 number of SCREENSIZE - 2 CARD16 CARD16 offset in LISTofREFRESH - 2 CARD16 number of CARD16 in refresh rates - - - RRSetMonitorConfig - - 1 CARD8 major opcode - 1 0x09 RandR opcode - 2 7 length - 4 DRAWABLE drawable - 4 TIMESTAMP timestamp - 4 TIMESTAMP config timestamp - 2 SIZEID size index - 2 ROTATION rotation/reflection - 2 CARD16 rate - 2 MONITOR monitor index - 2 INT16 x - 2 INT16 y - -> - 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 MONITOR monitor - 4 CARD32 pad6 - 4 CARD32 pad7 - - -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 - -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. diff --git a/randr.h b/randr.h index 5be0a3b..5975cdc 100644 --- a/randr.h +++ b/randr.h @@ -31,13 +31,18 @@ typedef unsigned short Rotation; typedef unsigned short SizeID; typedef unsigned short SubpixelOrder; +typedef unsigned short XRandrRotation; +typedef unsigned short XRandrSizeID; +typedef unsigned short XRandrSubpixelOrder; +typedef unsigned short XRandrModeID; +typedef unsigned short XRandrMonitor; #define RANDR_NAME "RANDR" #define RANDR_MAJOR 1 -#define RANDR_MINOR 1 +#define RANDR_MINOR 2 #define RRNumberErrors 0 -#define RRNumberEvents 1 +#define RRNumberEvents 2 #define X_RRQueryVersion 0 /* we skip 1 to make old clients fail pretty immediately */ @@ -50,11 +55,25 @@ typedef unsigned short SubpixelOrder; #define X_RRSelectInput 4 #define X_RRGetScreenInfo 5 -/* used in XRRSelectInput */ +/* V1.2 additions */ +#define X_RRGetScreenSizeRange 6 +#define X_RRSetScreenSize 7 +#define X_RRGetMonitorInfo 8 +#define X_RRAddMonitorMode 9 +#define X_RRDeleteMonitorMode 10 +#define X_RRSetMonitorConfig 11 +/* Event selection bits */ #define RRScreenChangeNotifyMask (1L << 0) +/* V1.2 additions */ +#define RRMonitorChangeNotifyMask (1L << 1) +/* Event codes */ #define RRScreenChangeNotify 0 +/* V1.2 additions */ +#define RRNotify 1 +/* RRNotify Subcodes */ +#define RRNotify_MonitorChange 0 /* used in the rotation field; rotation and reflection in 0.1 proto. */ #define RR_Rotate_0 1 @@ -72,4 +91,22 @@ typedef unsigned short SubpixelOrder; #define RRSetConfigInvalidTime 2 #define RRSetConfigFailed 3 +/* new in 1.2 protocol */ +#define RR_MonitorDisabled 0xffff + +#define RR_HSyncPositive 0x00000001 +#define RR_HSyncNegative 0x00000002 +#define RR_VSyncPositive 0x00000004 +#define RR_VSyncNegative 0x00000008 +#define RR_Interlace 0x00000010 +#define RR_DoubleScan 0x00000020 +#define RR_CSync 0x00000040 +#define RR_CSyncPositive 0x00000080 +#define RR_CSyncNegative 0x00000100 +#define RR_HSkewPresent 0x00000200 +#define RR_BCast 0x00000400 +#define RR_PixelMultiplex 0x00000800 +#define RR_DoubleClock 0x00001000 +#define RR_ClockDivideBy2 0x00002000 + #endif /* _RANDR_H_ */ diff --git a/randrproto.h b/randrproto.h index bfa3976..227a49b 100644 --- a/randrproto.h +++ b/randrproto.h @@ -47,6 +47,7 @@ #define Rotation CARD16 #define SizeID CARD16 #define SubpixelOrder CARD16 +#define ModeID CARD16 /* * data structures diff --git a/randrproto.txt b/randrproto.txt new file mode 100644 index 0000000..e929486 --- /dev/null +++ b/randrproto.txt @@ -0,0 +1,1023 @@ + 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: + o Modern toolkits (in this case, GTK+ 2.x) have progressed to the point + of implementing migration between screens of arbitrary depths + o 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 + o The continued decline of legacy toolkits whose design would have + required depth switching to support migration + o The lack of depth switchin 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 implementated 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, +the size of the 'porthole' shown by each monitor is independent of the +overall size of the screen, and the porthole may be located anywhere within +the screen. + +The effect is to decouple the reported size of the screen from the size +presented by each monitor, and to permit multiple monitors to present +information for a single screen. + +To extend RandR for this model, we separate out the monitor 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) monitor. +Monitor configuration is now done with full mode information instead of just +size and refresh rate, and these modes have names. These names should use +UTF-8 encoding, but there isn't any enforcement in the specification. +New modes may also be added by the user. + +Additional requests and events are provided for this new functionality. + +2. Acknowlegements + +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 + +2. Screen change model + +Screens may change dynamically, either under control of this +extension, or due to external events. Examples include: monitors being +swapped, you 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 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 enabel 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 stucture, 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 + +There are no new error types defined by this extension. + +5. Protocol Types + +RRCONFIGSTATUS { + Success + InvalidConfigTime + InvalidTime + Failed } +ROTATION { + Rotate_0 + Rotate_90 + Rotate_180 + Rotate_270 + Reflect_X + Reflect_Y } + +RRSELECTMASK { RRScreenChangeNotifyMask + RRMonitorChangeNotifyMask (New in version 1.2) } + +SIZEID { CARD16 } + +MODEID { CARD16 or Disabled } + +MONITOR { CARD16 } + +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 { + hsync_positive hsync_negative + vsync_positive vsync_negative + interlace double_scan + csync csync_positive csync_negative + hskew_present + bcast + pixel_multiplex + double_clock + clock_divide_by_2 +} + +MONITORMODE { + name: STRING + widthInPixels, heightInPixels: CARD16 + widthInMillimeters, heightInMillimeters: CARD32 + 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 RRMonitorChangeMask, + RRMonitorChangeNotify events will be sent when a the configuration + for a monitor associated with the screen changes, either through + this protocol extension or due to detected external monitor changes. + RRMonitorChangeNotify may also be sent when this request executes if + the monitor configuration has changed since the client connected, to + avoid race conditions. + +RRSetScreenConfig + drawable: DRAWABLE + 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 + drawable. + + '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 + + where: + + 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 cooresponding 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 monitor configuration, permitting the subset of the screen +presented by multiple monitors to be configured. As a separate notion, the +size of the screen itself may be arbitrarily configured within a defined +range. As monitors are added and removed from the system, the set returned +by RRGetMonitorModes will change so that applications can detect dynamic +changes in the monitor environment. + +RRGetScreenSizeRange + drawable: DRAWABLE + + -> + + CARD16 minWidth, minHeight + CARD16 maxWidth, maxHeight + + Errors: Drawable + + Returns the range of possible screen sizes. The screen may be set to + any size within this range. + +RRSetScreenSize + drawable: DRAWABLE + width: CARD16 + height: CARD16 + + Errors: Drawable, 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. + +RRGetMonitorModes + drawable: DRAWABLE + + -> + + root: WINDOW + monitors: LISTofMONITORINFO + + where: + + MONITORINFO { + timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + x, y: INT16 + mode: MODEID + rotation: ROTATION + rotations: SETofROTATION + default-mode: MODEID + modes: LISTofMONITORMODE + } + + Errors: Drawable + + RRGetMonitorInfo returns information about the current and available + configurations for all monitors connected to the screen associated + with 'window'. + + 'root' is the root window of the screen. + + 'timestamp' indicates when the configuration was last set. + + '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. + + 'x' and 'y' indicate the position of this monitor within the screen + region. They will be set to 0 when the monitor is disabled. + + 'mode' indicates which mode is active, or 'Disabled' indicating + that the monitor has been disabled and is not displaying the screen + contents. + + 'rotation' indicates the active rotation. It is set to Rotate_0 + when the monitor is disabled. + + 'rotations' contains the set of rotations and reflections supported + by the monitor. + + 'default-mode' is the mode the monitor is set to at server + reset time. + + 'modes' is the list of possible displayed modes. Within each mode, + the sizes are reported for rotation set to Rotate_0. + +RRAddMonitorMode + drawable: DRAWABLE + monitor-index: MONITOR + mode: MONITORMODE + config-timestamp: TIMESTAMP + timestamp: TIMESTAMP + + -> + + Errors: Drawable, Value, Match, Name + + 'drawable' and 'monitor-index' indicate which monitor is to be + configured. If 'monitor-index' is out of range, a Value error is + returned. + + 'mode' provides a new mode for the monitor. If the name of 'mode' + names an existing mode, a Name error is returned. If 'mode' cannot be + supported by the specified monitor, a Match error is returned. If + some parameter of the mode is not valid in some other way, a Value + error is returned. + + This request generates MonitorChangeNotify events. + +RRDeleteMonitorMode + drawable: DRAWABLE + monitor-index: MONITOR + name: STRING + + -> + + Errors: Drawable, Value, Name + + 'drawable' and 'monitor-index' indicate which monitor is to be + configured. If 'monitor-index' is out of range, a Value error is + returned. + + 'name' specifies which mode to delete. If no mode of the specified + name exists, a Name error is returned. The named mode must have + been added with RRAddMonitorMode, else an Access error is returned. + The named mode must not be active, else a Match error is returned. + +RRSetMonitorMode + drawable: DRAWABLE + monitor-index: MONITOR + timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + x, y: INT16 + mode: MODEID + rotation: ROTATION + + -> + + status: RRCONFIGSTATUS + new-timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + root: WINDOW + monitor: MONITOR + 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 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' contains the index of desired mode or Disabled indicating the + monitor should be disabled. If 'mode' is not one of these values, a + Value error results. + + '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. + + 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 monitor to the specified position, mode, + rotation and reflection. The entire area of the monitor must fit + within the screen size, else a Match error results. As an example, + rotating the screen so that a single monitor fills the entire screen + before and after may necessitate disabling the monitor, resizing the + screen, then re-enabling the monitor 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. + + 'config-timestamp' contains the time when the possible screen + configurations were last changed. + + 'root' contains the root window for the screen indicated by the + drawable. + + 'subpixelOrder' contains the resulting subpixel order of the monitor + to allow correct subpixel rendering. + +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 +clients need 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 recabling a monitor, etc. + +RRScreenChangeNotify + + rotation: ROTATION; new rotation + sequenceNumber: CARD16 low 16 bits of request's 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 + +RRMonitorChangeNotify + + rotation: ROTATION; new rotation + sequenceNumber: CARD16 low 16 bits of request's seq. number + timestamp: TIMESTAMP time monitor was changed + configTimestamp: TIMESTAMP time config data was changed + root: WINDOW root window of screen + window: WINDOW window requesting notification + monitor-index: MONITOR monitor which changed + mode: MODEID new mode + subpixelOrder: SUBPIXELORDER order of subpixels + x: INT16 x position of monitor within screen + y: INT16 y position of monitor within screen + + This event is generated whenever the monitor configuration is changed + and sent to requesting clients. 'timestamp' indicates when the + monitor 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 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 RRGetMonitorInfo), the client MUST call + RRGetMonitorInfo 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 provied. +This document describes the version 1.0 of the specification, the +partial implementations have version numbers less than that. Here's a +list of what each version before 1.0 implemented: + + 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 out screens from monitors, 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. + +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. + +Most of the utility of this extension is subsumed by RandR version 1.2, +except for the gamma adjustments. If this features continue to be useful, +either some relationship between the screen indices used in the +XFree86-VidModeExtension and the screen/monitor pairs used int RandR or an +incorporation of this functionality into RandR might be needed. + +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 + + + RRSELECTMASK + 0x0001 ScreenChangeNotifyMask + 0x0002 MonitorChangeNotifyMask Added in version 1.2 + + RRCONFIGSTATUS + 0x0 Success + 0x1 InvalidConfigTime + 0x2 InvalidTime + 0x3 Failed + + SIZEID + 0xffff Disabled + + MONITORMODE (36) Added in version 1.2 + 2 CARD16 width in pixels + 2 CARD16 height in pixels + 4 CARD32 width in millimeters + 4 CARD32 height in millimeters + 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 (n) + 4 SETofMODEFLAG mode flags + + The location of the name in the encoding is specified separately + +A.2 Protocol Requests + + +Opcodes 0x1 and 0x3 were used in the 0.0 protocols, and will return +errors if used in version 1.0. + + RRQueryVersion + + 1 CARD8 major opcode + 1 0x01 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 0x02 RandR opcode + 2 6 length + 4 DRAWABLE drawable 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 0x04 RandR opcode + 2 3 length + 4 WINDOW window + 2 SETofRRSELECTMASK enable + 2 CARD16 pad + + + RRGetScreenInfo + + 1 CARD8 major opcode + 1 0x05 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 0x06 RandR opcode + 2 2 length + 4 DRAWABLE drawable + -> + 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 + 4 unused + 4 unused + 4 unused + 4 unused + + + RRSetScreenSize + + 1 CARD8 major opcode + 1 0x07 RandR opcode + 2 3 length + 4 DRAWABLE drawable + 2 CARD16 width + 2 CARD16 height + + + RRGetMonitorInfo + + 1 CARD8 major opcode + 1 0x08 RandR opcode + 2 2 length + 4 DRAWABLE drawable + -> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 i*6 + m*9 + (b+p)/4 reply length + 4 WINDOW root + 2 CARD16 i = number of MONITORINFO following + 2 CARD16 m = number of SIZE following + 2 CARD16 b = size of name array following + 14 unused + i*24 LISTofMONITORINFO one per monitor + m*36 LISTofMONITORMODE for all monitors + b LISTofCARD* list of mode names + p pad pad(b) + + MONITORINFO + 4 TIMESTAMP timestamp + 4 TIMESTAMP config-timestamp + 2 INT16 x + 2 INT16 y + 2 ROTATION rotation + 2 MODEID mode + 2 MODEID default mode + 2 SETofROTATION rotations + 2 CARD16 start offset in LISTofMONITORMODE + 2 CARD16 number of MONITORMODE + + RRAddMonitorMode + 1 CARD8 major opcode + 1 0x09 RandR opcode + 2 9+(b+p)/4 length + 4 DRAWABLE drawable + 2 MONITOR monitor index + 2 unused + 24 MONITORMODE mode + b STRING mode name + p pad(b) + + RRDeleteMonitorMode + 1 CARD8 major opcode + 1 0x0a RandR opcode + 2 3+(b+p)/4 length + 4 DRAWABLE drawable + 2 MONITOR monitor index + 2 CARD16 mode name length + b STRING mode name + p pad(b) + + RRSetMonitorConfig + + 1 CARD8 major opcode + 1 0x0b RandR opcode + 2 7 length + 4 DRAWABLE drawable + 4 TIMESTAMP timestamp + 4 TIMESTAMP config timestamp + 2 SIZEID size index + 2 ROTATION rotation/reflection + 2 CARD16 rate + 2 MONITOR monitor index + 2 INT16 x + 2 INT16 y + -> + 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 MONITOR monitor + 4 CARD32 pad6 + 4 CARD32 pad7 + + +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 + + RRMonitorChangeNotify + + 1 Base + 1 code + 1 0 sub-code + 2 CARD16 sequence number + 4 TIMESTAMP timestamp + 4 TIMESTAMP configuration timestamp + 4 WINDOW root window + 4 WINDOW request window + 2 MONITOR monitor index + 2 MODEID mode ID + 2 CARD16 x + 2 CARD16 y + 1 ROTATION new rotation and reflection + 3 unused + +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. -- cgit v1.2.1