diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | COPYING | 49 | ||||
| -rw-r--r-- | ChangeLog | 4 | ||||
| -rw-r--r-- | Makefile.am | 2 | ||||
| -rw-r--r-- | configure.ac | 2 | ||||
| -rw-r--r-- | protocol.txt | 519 | ||||
| -rw-r--r-- | randr.h | 109 | ||||
| -rw-r--r-- | randrproto.h | 479 | ||||
| -rw-r--r-- | randrproto.txt | 1765 |
9 files changed, 2331 insertions, 599 deletions
@@ -1,3 +1,4 @@ +*~ Makefile Makefile.in aclocal.m4 @@ -1,40 +1,21 @@ -Copyright © 2000, Compaq Computer Corporation, -Copyright © 2002, Hewlett Packard, Inc. - -Permission to use, copy, modify, distribute, and sell this software and its -documentation for any purpose is hereby granted without fee, provided that -the above copyright notice appear in all copies and that both that -copyright notice and this permission notice appear in supporting -documentation, and that the name of Compaq or HP not be used in advertising -or publicity pertaining to distribution of the software without specific, -written prior permission. HP makes no representations about the -suitability of this software for any purpose. It is provided "as is" -without express or implied warranty. - -HP DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL HP -BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION -OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN -CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - - Copyright © 2000 Compaq Computer Corporation Copyright © 2002 Hewlett-Packard Company +Copyright © 2006 Intel Corporation Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that -the above copyright notice appear in all copies and that both that -copyright notice and this permission notice appear in supporting -documentation, and that the name of Compaq or HP not be used in advertising -or publicity pertaining to distribution of the software without specific, -written prior permission. Compaq and HP makes no representations about the -suitability of this software for any purpose. It is provided "as is" -without express or implied warranty. +the above copyright notice appear in all copies and that both that copyright +notice and this permission notice appear in supporting documentation, and +that the name of the copyright holders not be used in advertising or +publicity pertaining to distribution of the software without specific, +written prior permission. The copyright holders make no representations +about the suitability of this software for any purpose. It is provided "as +is" without express or implied warranty. -HP DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL COMPAQ -BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION -OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN -CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, +INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO +EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR +CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, +DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER +TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE +OF THIS SOFTWARE. diff --git a/ChangeLog b/ChangeLog deleted file mode 100644 index c722b51..0000000 --- a/ChangeLog +++ /dev/null @@ -1,4 +0,0 @@ -2005-12-14 Kevin E. Martin <kem-at-freedesktop-dot-org> - - * configure.ac: - Update package version number for final X11R7 release candidate. 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/configure.ac b/configure.ac index 2842ccf..ac3a617 100644 --- a/configure.ac +++ b/configure.ac @@ -1,5 +1,5 @@ AC_PREREQ([2.57]) -AC_INIT([RandrProto], [1.1.2], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg]) +AC_INIT([RandrProto], [1.2.0], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg]) AM_INIT_AUTOMAKE([foreign dist-bzip2]) XORG_RELEASE_VERSION diff --git a/protocol.txt b/protocol.txt deleted file mode 100644 index aa15f83..0000000 --- a/protocol.txt +++ /dev/null @@ -1,519 +0,0 @@ - The X Resize, Rotate and Reflect Extension - Version 1.0 - 2002-10-4 - - Jim Gettys - Jim.Gettys@hp.com - - Keith Packard - keithp@xfree86.org - - Cambridge Research Laboratory - HP Labs - Hewlett Packard Company - -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 XFree86 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 XFree86 implementationhas 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 XFree86 server, and more fully in the TinyX implementation in the -XFree86 distribution, which fully implements resizing, rotation and -reflection. - -2. Acknowlegements - -Our thanks to the contributors to the design found on the xpert mailing list. - -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 - -ROTATION { - RR_rotate_0 - RR_rotate_90 - RR_rotate_180 - RR_rotate_270 - RR-Reflect_X - RR_Reflect_Y } - -RRSELECTMASK { RRScreenChangeNotifyMask } - -SIZEID { CARD16 } - -SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render - SubPixelHorizontalRGB extensions definitions; they are here - SubPixelHorizontalBGR only for convenience. - SubPixelVerticalRGB - SubPixelVerticalBGR - SubPixelNone } - - -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: BadWindow, BadValue - - If enable is RRScreenChangeNotifyMask, RRScreenChangeNotify - events will be sent anytime the screen configuration changes, - either from this protocol extension, or due to detected - external screen configuration changes. RRScreenChangeNotify - may also be sent immediately if the screen configuration has - changed since the client connected, to avoid race conditions. - -RRSetScreenConfig - drawable: DRAWABLE - timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - sizeID: SIZEID - rotation: ROTATION - rate: CARD16 - - -> - - new-timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - root: WINDOW - subpixelOrder: SUBPIXELORDER - - Errors: BadValue, BadMatch - - If the timestamp in this request is less than the time when - the configuration was last successfully set, the request is - ignored and False returned in success. If the - config-timestamp in this request is not equal to when the - server's screen configurations last changed, the request is - ignored and False returned in success. 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. - - If rate is zero, the server selects an appropriate rate. - - If the request succeeds, this request sets the screen to the - specified size, rate, rotation and reflection. If the requests - succeeds, the new-time-stamp is returned containing the time - when the screen configuration was changed and config-timestamp - is returned to indicate when the possible screen - configurations were last changed, and success is set to True. - The root window for the screen indicated by the drawable - argument is also returned, along with the subpixel order, to - allow correct subpixel rendering. - - BadValue errors are generated if the rotation is not an - allowed rotation. BadValue errors are generated, if, when the - timestamps would allow the operation to succeed, or size-index - are not possible (out of range). - - -RRGetScreenInfo - window: WINDOW - - -> - - rotations: SETofROTATION - root: WINDOW - timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - nSizes: CARD16 - sizeID: SIZEID - rotation: ROTATION - rate: CARD16 - sizes: LISTofSCREENSIZE - refresh: LISTofREFRESH - - where: - - SCREENSIZE { - widthInPixels, heightInPixels: CARD16 - widthInMillimeters, heightInMillimeters: CARD16 } - - REFRESH { - rates: LISTofCARD16 - } - - Errors: BadWindow - - This event is delivered to clients selecting for notification - with RRSelectInput requests using a RRScreenChangeNotifyMask. - - Size-index indicates which size is active. The returned - window is the window requsting notification. - - This call returns the root window of the screen which has changed. - - Rotations contains the set of rotations and reflections - supported by the screen of the window requested. The root - window of that screen is reported. The number of current sizes - supported is returned, along with which size rotation and - reflection the screen is currently set to. - - The 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. Similarly, timestamp indicates - when the configuration was last set, and must both must be up - to date in a call to RRSetScreenConfig for it to succeed. - - 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 provide 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. The potential screen sizes themselves are also - returned. - - Toolkits SHOULD use RRScreenChangeSelectInput to be notified - via a RRScreenChangeNotify event, so that they can adapt to - screen size changes. - - -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 - sizeID: SIZEID new ID of size - subpixelOrder: SUBPIXELORDER order of subpixels - widthInPixels: INT16 - heightInPixels: INT16 - widthInMillimeters: INT16 - heightInMillimeters: INT16 - - This event is generated whenever the screen configuration is - changed and sent to requesting clients. The timestamp included - indicates when the screen configuration was changed, and - configTimestamp says when the last time the configuration was - changed. The root is the root of the screen the change - occurred on, and the event window is also returned. SizeID - contains an index indicating which size is current. - - 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. Timestamp is set to when the active screen - configuration was changed. - - 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. - - -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 - -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. - - -Appendix A. Protocol Encoding - -Syntactic Conventions - -This document uses the same syntactic conventions as the core X -protocol encoding document. - - -A.1 Common Types - - SETofROTATION - - 0x0001 RR_Rotate_0 - 0x0002 RR_Rotate_90 - 0x0004 RR_Rotate_180 - 0x0008 RR_Rotate_270 - 0x0010 RR_Reflect_X - 0x0020 RR_Reflect_Y - - - SETofRRSELECTMASK - - 0x0001 RRScreenChangeNotifyMask - - -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 5 length - 4 DRAWABLE drawable on screen to be configured - 4 TIMESTAMP timestamp - 2 SIZEID size id - 2 ROTATION rotation/reflection - 2 CARD16 refresh rate (1.1 only) - 2 CARD16 pad - -> - 1 1 Reply - 1 CARD8 status - 0x0 RRSetConfigSuccess - 0x1 RRSetConfigInvalidConfigTime - 0x2 RRSetConfigInvalidTime - 0x3 RRSetConfigFailed - 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 SIZE following - 2 SIZEID sizeID - 2 ROTATION current rotation and reflection - 2 CARD16 rate (1.1) - 2 CARD16 length of rate info (number of CARD16s) - 2 CARD16 pad - - SIZE - 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 Protocol Event - - 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 - - -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. @@ -1,27 +1,28 @@ /* - * $XFree86: xc/include/extensions/randr.h,v 1.4 2001/11/24 07:24:58 keithp Exp $ - * - * Copyright © 2000, Compaq Computer Corporation, - * Copyright © 2002, Hewlett Packard, Inc. + * Copyright © 2000 Compaq Computer Corporation + * Copyright © 2002 Hewlett Packard Company + * Copyright © 2006 Intel Corporation * * Permission to use, copy, modify, distribute, and sell this software and its * documentation for any purpose is hereby granted without fee, provided that - * the above copyright notice appear in all copies and that both that - * copyright notice and this permission notice appear in supporting - * documentation, and that the name of Compaq or HP not be used in advertising - * or publicity pertaining to distribution of the software without specific, - * written prior permission. HP makes no representations about the - * suitability of this software for any purpose. It is provided "as is" - * without express or implied warranty. + * the above copyright notice appear in all copies and that both that copyright + * notice and this permission notice appear in supporting documentation, and + * that the name of the copyright holders not be used in advertising or + * publicity pertaining to distribution of the software without specific, + * written prior permission. The copyright holders make no representations + * about the suitability of this software for any purpose. It is provided "as + * is" without express or implied warranty. * - * HP DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL HP - * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION - * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN - * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR + * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE + * OF THIS SOFTWARE. * * Author: Jim Gettys, HP Labs, Hewlett-Packard, Inc. + * Keith Packard, Intel Corporation */ #ifndef _RANDR_H_ @@ -30,13 +31,19 @@ typedef unsigned short Rotation; typedef unsigned short SizeID; typedef unsigned short SubpixelOrder; +typedef unsigned short Connection; +typedef unsigned short XRandrRotation; +typedef unsigned short XRandrSizeID; +typedef unsigned short XRandrSubpixelOrder; +typedef unsigned long XRandrModeFlags; #define RANDR_NAME "RANDR" #define RANDR_MAJOR 1 -#define RANDR_MINOR 1 +#define RANDR_MINOR 2 -#define RRNumberErrors 0 -#define RRNumberEvents 1 +#define RRNumberErrors 3 +#define RRNumberEvents 2 +#define RRNumberRequests 25 #define X_RRQueryVersion 0 /* we skip 1 to make old clients fail pretty immediately */ @@ -49,11 +56,42 @@ 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_RRGetScreenResources 8 +#define X_RRGetOutputInfo 9 +#define X_RRListOutputProperties 10 +#define X_RRQueryOutputProperty 11 +#define X_RRConfigureOutputProperty 12 +#define X_RRChangeOutputProperty 13 +#define X_RRDeleteOutputProperty 14 +#define X_RRGetOutputProperty 15 +#define X_RRCreateMode 16 +#define X_RRDestroyMode 17 +#define X_RRAddOutputMode 18 +#define X_RRDeleteOutputMode 19 +#define X_RRGetCrtcInfo 20 +#define X_RRSetCrtcConfig 21 +#define X_RRGetCrtcGammaSize 22 +#define X_RRGetCrtcGamma 23 +#define X_RRSetCrtcGamma 24 +/* Event selection bits */ #define RRScreenChangeNotifyMask (1L << 0) +/* V1.2 additions */ +#define RRCrtcChangeNotifyMask (1L << 1) +#define RROutputChangeNotifyMask (1L << 2) +#define RROutputPropertyNotifyMask (1L << 3) +/* Event codes */ #define RRScreenChangeNotify 0 +/* V1.2 additions */ +#define RRNotify 1 +/* RRNotify Subcodes */ +#define RRNotify_CrtcChange 0 +#define RRNotify_OutputChange 1 +#define RRNotify_OutputProperty 2 /* used in the rotation field; rotation and reflection in 0.1 proto. */ #define RR_Rotate_0 1 @@ -71,4 +109,33 @@ typedef unsigned short SubpixelOrder; #define RRSetConfigInvalidTime 2 #define RRSetConfigFailed 3 +/* new in 1.2 protocol */ + +#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 + +#define RR_Connected 0 +#define RR_Disconnected 1 +#define RR_UnknownConnection 2 + +#define BadRROutput 0 +#define BadRRCrtc 1 +#define BadRRMode 2 + +/* Conventional RandR output properties */ + +#define RR_PROPERTY_RANDR_EDID "RANDR_EDID" + #endif /* _RANDR_H_ */ diff --git a/randrproto.h b/randrproto.h index 04d62fc..fe40c0e 100644 --- a/randrproto.h +++ b/randrproto.h @@ -1,27 +1,28 @@ /* - * $XFree86: xc/include/extensions/randrproto.h,v 1.6 2002/09/29 23:39:43 keithp Exp $ - * * Copyright © 2000 Compaq Computer Corporation * Copyright © 2002 Hewlett-Packard Company + * Copyright © 2006 Intel Corporation * * Permission to use, copy, modify, distribute, and sell this software and its * documentation for any purpose is hereby granted without fee, provided that - * the above copyright notice appear in all copies and that both that - * copyright notice and this permission notice appear in supporting - * documentation, and that the name of Compaq or HP not be used in advertising - * or publicity pertaining to distribution of the software without specific, - * written prior permission. Compaq and HP makes no representations about the - * suitability of this software for any purpose. It is provided "as is" - * without express or implied warranty. + * the above copyright notice appear in all copies and that both that copyright + * notice and this permission notice appear in supporting documentation, and + * that the name of the copyright holders not be used in advertising or + * publicity pertaining to distribution of the software without specific, + * written prior permission. The copyright holders make no representations + * about the suitability of this software for any purpose. It is provided "as + * is" without express or implied warranty. * - * HP DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL COMPAQ - * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION - * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN - * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR + * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE + * OF THIS SOFTWARE. * * Author: Jim Gettys, Hewlett-Packard Company, Inc. + * Keith Packard, Intel Corporation */ /* note that RANDR 1.0 is incompatible with version 0.0, or 0.1 */ @@ -42,6 +43,10 @@ #define Time CARD32 #define KeyCode CARD8 #define KeySym CARD32 +#define RROutput CARD32 +#define RRMode CARD32 +#define RRCrtc CARD32 +#define RRModeFlags CARD32 #define Rotation CARD16 #define SizeID CARD16 @@ -169,7 +174,388 @@ typedef struct { } xRRSelectInputReq; #define sz_xRRSelectInputReq 12 -#define sz_xRRSelectInputReq 12 +/* + * Additions for version 1.2 + */ + +typedef struct _xRRModeInfo { + RRMode id B32; + CARD16 width B16; + CARD16 height B16; + CARD32 dotClock B32; + CARD16 hSyncStart B16; + CARD16 hSyncEnd B16; + CARD16 hTotal B16; + CARD16 hSkew B16; + CARD16 vSyncStart B16; + CARD16 vSyncEnd B16; + CARD16 vTotal B16; + CARD16 nameLength B16; + RRModeFlags modeFlags B32; +} xRRModeInfo; +#define sz_xRRModeInfo 32 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + Window window B32; +} xRRGetScreenSizeRangeReq; +#define sz_xRRGetScreenSizeRangeReq 8 + +typedef struct { + BYTE type; /* X_Reply */ + CARD8 pad; + CARD16 sequenceNumber B16; + CARD32 length B32; + CARD16 minWidth B16; + CARD16 minHeight B16; + CARD16 maxWidth B16; + CARD16 maxHeight B16; + CARD32 pad0 B32; + CARD32 pad1 B32; + CARD32 pad2 B32; + CARD32 pad3 B32; +} xRRGetScreenSizeRangeReply; +#define sz_xRRGetScreenSizeRangeReply 32 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + Window window B32; + CARD16 width B16; + CARD16 height B16; + CARD32 widthInMillimeters B32; + CARD32 heightInMillimeters B32; +} xRRSetScreenSizeReq; +#define sz_xRRSetScreenSizeReq 20 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + Window window B32; +} xRRGetScreenResourcesReq; +#define sz_xRRGetScreenResourcesReq 8 + +typedef struct { + BYTE type; + CARD8 pad; + CARD16 sequenceNumber B16; + CARD32 length B32; + Time timestamp B32; + Time configTimestamp B32; + CARD16 nCrtcs B16; + CARD16 nOutputs B16; + CARD16 nModes B16; + CARD16 nbytesNames B16; + CARD32 pad1 B32; + CARD32 pad2 B32; +} xRRGetScreenResourcesReply; +#define sz_xRRGetScreenResourcesReply 32 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RROutput output B32; + Time configTimestamp B32; +} xRRGetOutputInfoReq; +#define sz_xRRGetOutputInfoReq 12 + +typedef struct { + BYTE type; + CARD8 status; + CARD16 sequenceNumber B16; + CARD32 length B32; + Time timestamp B32; + RRCrtc crtc B32; + CARD32 mmWidth B32; + CARD32 mmHeight B32; + CARD8 connection; + CARD8 subpixelOrder; + CARD16 nCrtcs B16; + CARD16 nModes B16; + CARD16 nPreferred B16; + CARD16 nClones B16; + CARD16 nameLength B16; +} xRRGetOutputInfoReply; +#define sz_xRRGetOutputInfoReply 36 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RROutput output B32; +} xRRListOutputPropertiesReq; +#define sz_xRRListOutputPropertiesReq 8 + +typedef struct { + BYTE type; + CARD8 nProperties; + CARD16 sequenceNumber B16; + CARD32 length B32; + CARD16 nAtoms B16; + CARD16 pad1 B16; + CARD32 pad2 B32; + CARD32 pad3 B32; + CARD32 pad4 B32; + CARD32 pad5 B32; + CARD32 pad6 B32; +} xRRListOutputPropertiesReply; +#define sz_xRRListOutputPropertiesReply 32 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RROutput output B32; + Atom property B32; +} xRRQueryOutputPropertyReq; +#define sz_xRRQueryOutputPropertyReq 12 + +typedef struct { + BYTE type; + BYTE pad0; + CARD16 sequenceNumber B16; + CARD32 length B32; + BOOL pending; + BOOL range; + BOOL immutable; + BYTE pad1; + CARD16 pad2 B16; + CARD32 pad3 B32; + CARD32 pad4 B32; + CARD32 pad5 B32; + CARD32 pad6 B32; +} xRRQueryOutputPropertyReply; +#define sz_xRRQueryOutputPropertyReply 32 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RROutput output B32; + Atom property B32; + BOOL pending; + BOOL range; + CARD16 pad B16; +} xRRConfigureOutputPropertyReq; +#define sz_xRRConfigureOutputPropertyReq 16 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RROutput output B32; + Atom property B32; + Atom type B32; + CARD8 format; + CARD8 mode; + CARD16 pad; + CARD32 nUnits B32; +} xRRChangeOutputPropertyReq; +#define sz_xRRChangeOutputPropertyReq 24 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RROutput output B32; + Atom property B32; +} xRRDeleteOutputPropertyReq; +#define sz_xRRDeleteOutputPropertyReq 12 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RROutput output B32; + Atom property B32; + Atom type B32; + CARD32 longOffset B32; + CARD32 longLength B32; + BOOL delete; + BOOL pending; + CARD16 pad1 B16; +} xRRGetOutputPropertyReq; +#define sz_xRRGetOutputPropertyReq 28 + +typedef struct { + BYTE type; + CARD8 format; + CARD16 sequenceNumber B16; + CARD32 length B32; + Atom propertyType B32; + CARD32 bytesAfter B32; + CARD32 nItems B32; + CARD32 pad1 B32; + CARD32 pad2 B32; + CARD32 pad3 B32; +} xRRGetOutputPropertyReply; +#define sz_xRRGetOutputPropertyReply 32 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + Window window B32; + xRRModeInfo modeInfo; +} xRRCreateModeReq; +#define sz_xRRCreateModeReq 40 + +typedef struct { + BYTE type; + CARD8 status; + CARD16 sequenceNumber B16; + CARD32 length B32; + RRMode mode B32; + CARD32 pad1 B32; + CARD32 pad2 B32; + CARD32 pad3 B32; + CARD32 pad4 B32; + CARD32 pad5 B32; +} xRRCreateModeReply; +#define sz_xRRCreateModeReply 32 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RRMode mode B32; +} xRRDestroyModeReq; +#define sz_xRRDestroyModeReq 8 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RROutput output B32; + RRMode mode B32; +} xRRAddOutputModeReq; +#define sz_xRRAddOutputModeReq 12 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RROutput output B32; + RRMode mode B32; +} xRRDeleteOutputModeReq; +#define sz_xRRDeleteOutputModeReq 12 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RRCrtc crtc B32; + Time configTimestamp B32; +} xRRGetCrtcInfoReq; +#define sz_xRRGetCrtcInfoReq 12 + +typedef struct { + BYTE type; + CARD8 status; + CARD16 sequenceNumber B16; + CARD32 length B32; + Time timestamp B32; + INT16 x B16; + INT16 y B16; + CARD16 width B16; + CARD16 height B16; + RRMode mode B32; + Rotation rotation B16; + Rotation rotations B16; + CARD16 nOutput B16; + CARD16 nPossibleOutput B16; +} xRRGetCrtcInfoReply; +#define sz_xRRGetCrtcInfoReply 32 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RRCrtc crtc B32; + Time timestamp B32; + Time configTimestamp B32; + INT16 x B16; + INT16 y B16; + RRMode mode B32; + Rotation rotation B16; + CARD16 pad B16; +} xRRSetCrtcConfigReq; +#define sz_xRRSetCrtcConfigReq 28 + +typedef struct { + BYTE type; + CARD8 status; + CARD16 sequenceNumber B16; + CARD32 length B32; + Time newTimestamp B32; + CARD32 pad1 B32; + CARD32 pad2 B16; + CARD32 pad3 B32; + CARD32 pad4 B32; + CARD32 pad5 B32; +} xRRSetCrtcConfigReply; +#define sz_xRRSetCrtcConfigReply 32 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RRCrtc crtc B32; +} xRRGetCrtcGammaSizeReq; +#define sz_xRRGetCrtcGammaSizeReq 8 + +typedef struct { + BYTE type; + CARD8 status; + CARD16 sequenceNumber B16; + CARD32 length B32; + CARD16 size B16; + CARD16 pad1 B16; + CARD16 pad2 B32; + CARD16 pad3 B32; + CARD16 pad4 B32; + CARD16 pad5 B32; + CARD16 pad6 B32; +} xRRGetCrtcGammaSizeReply; +#define sz_xRRGetCrtcGammaSizeReply 32 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RRCrtc crtc B32; +} xRRGetCrtcGammaReq; +#define sz_xRRGetCrtcGammaReq 8 + +typedef struct { + BYTE type; + CARD8 status; + CARD16 sequenceNumber B16; + CARD32 length B32; + CARD16 size B16; + CARD16 pad1 B16; + CARD16 pad2 B32; + CARD16 pad3 B32; + CARD16 pad4 B32; + CARD16 pad5 B32; + CARD16 pad6 B32; +} xRRGetCrtcGammaReply; +#define sz_xRRGetCrtcGammaReply 32 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RRCrtc crtc B32; + CARD16 size B16; + CARD16 pad1 B16; +} xRRSetCrtcGammaReq; +#define sz_xRRSetCrtcGammaReq 12 /* * event @@ -178,8 +564,8 @@ typedef struct { CARD8 type; /* always evBase + ScreenChangeNotify */ CARD8 rotation; /* new rotation */ CARD16 sequenceNumber B16; - Time timestamp B32; /* time screen was changed */ - Time configTimestamp B32; /* time config data was changed */ + Time timestamp B32; B32; /* time screen was changed */ + Time configTimestamp B32; B32; /* time config data was changed */ Window root B32; /* root window */ Window window B32; /* window requesting notification */ SizeID sizeID B16; /* new size ID */ @@ -191,8 +577,63 @@ typedef struct { } xRRScreenChangeNotifyEvent; #define sz_xRRScreenChangeNotifyEvent 32 -#undef Window +typedef struct { + CARD8 type; /* always evBase + RRNotify */ + CARD8 subCode; /* RRNotify_CrtcChange */ + CARD16 sequenceNumber B16; + Time timestamp B32; /* time crtc was changed */ + Window window B32; /* window requesting notification */ + RRCrtc crtc B32; /* affected CRTC */ + RRMode mode B32; /* current mode */ + CARD16 rotation B16; /* rotation and reflection */ + CARD16 pad1 B16; /* unused */ + INT16 x B16; /* new location */ + INT16 y B16; + CARD16 width B16; /* new size */ + CARD16 height B16; +} xRRCrtcChangeNotifyEvent; +#define sz_xRRCrtcChangeNotifyEvent 32 + +typedef struct { + CARD8 type; /* always evBase + RRNotify */ + CARD8 subCode; /* RRNotify_OutputChange */ + CARD16 sequenceNumber B16; + Time timestamp B32; /* time crtc was changed */ + Time configTimestamp B32; /* time crtc was changed */ + Window window B32; /* window requesting notification */ + RROutput output B32; /* affected output */ + RRCrtc crtc B32; /* current crtc */ + RRMode mode B32; /* current mode */ + CARD16 rotation B16; /* rotation and reflection */ + CARD8 connection; /* connection status */ + CARD8 subpixelOrder; /* subpixel order */ +} xRROutputChangeNotifyEvent; +#define sz_xRROUtputChangeNotifyEvent 32 + +typedef struct { + CARD8 type; /* always evBase + RRNotify */ + CARD8 subCode; /* RRNotify_OutputProperty */ + CARD16 sequenceNumber B16; + Window window B32; /* window requesting notification */ + RROutput output B32; /* affected output */ + Atom atom B32; /* property name */ + Time timestamp B32; /* time crtc was changed */ + CARD8 state; /* NewValue or Deleted */ + CARD8 pad1; + CARD16 pad2 B16; + CARD32 pad3 B32; + CARD32 pad4 B32; +} xRROutputPropertyNotifyEvent; +#define sz_xRROUtputPropertyNotifyEvent 32 + +#undef RRModeFlags +#undef RRCrtc +#undef RRMode +#undef RROutput +#undef RRMode +#undef RRCrtc #undef Drawable +#undef Window #undef Font #undef Pixmap #undef Cursor diff --git a/randrproto.txt b/randrproto.txt new file mode 100644 index 0000000..bde1fdf --- /dev/null +++ b/randrproto.txt @@ -0,0 +1,1765 @@ + 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 +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 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 +└─── +┌─── + 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 +└─── + +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. |