From 79af1c0351dbac7c89433b7ae141835a4566c428 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sat, 24 Jun 2006 16:14:07 -0700 Subject: Introduce Xinerama changes. Remove spurious 'Bad' error name prefix. --- protocol.txt | 70 ++++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 54 insertions(+), 16 deletions(-) diff --git a/protocol.txt b/protocol.txt index aa15f83..282f60f 100644 --- a/protocol.txt +++ b/protocol.txt @@ -1,16 +1,17 @@ The X Resize, Rotate and Reflect Extension - Version 1.0 - 2002-10-4 + Version 1.2 + 2006-4-13 Jim Gettys Jim.Gettys@hp.com - - Keith Packard - keithp@xfree86.org - Cambridge Research Laboratory - HP Labs - Hewlett Packard Company + HP Labs + Hewlett Packard Company + + Keith Packard + keith.packard@intel.com + Open Source Technology Center + Intel Corporation 1. Introduction @@ -19,7 +20,7 @@ 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 +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 @@ -53,6 +54,26 @@ main XFree86 server, and more fully in the TinyX implementation in the XFree86 distribution, which fully implements resizing, rotation and reflection. +1.2 Introduction to version 1.2 of the extension + +One of the significant limitations found in version 1.1 of the RandR +protocol was the inability to deal with the Xinerama model where multiple +monitors display portions of a common underlying screen. In this environment, +the size of the 'porthole' shown by each monitor is independent of the +overall size of the screen, and the porthole may be located anywhere within +the screen. + +The effect is to decouple the reported size of the screen from the size +presented by each monitor, and to permit multiple monitors to present +information for a single screen. + +To extend RandR for this model, we separate out the monitor and screen +configuration information and permit them to be configured separately. For +compatibility with the 1.1 version of the protocol, we make the 1.1 requests +simultaneously affect both the screen and the (presumably sole) monitor. + +Additional requests and events are provided for this new functionality. + 2. Acknowlegements Our thanks to the contributors to the design found on the xpert mailing list. @@ -107,7 +128,6 @@ 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. @@ -133,7 +153,6 @@ SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render SubPixelVerticalBGR SubPixelNone } - 6. Extension Initialization The name of this extension is "RANDR". @@ -159,7 +178,7 @@ RRSelectInput window: WINDOW enable: SETofRRSELECTMASK - Errors: BadWindow, BadValue + Errors: Window, Value If enable is RRScreenChangeNotifyMask, RRScreenChangeNotify events will be sent anytime the screen configuration changes, @@ -183,7 +202,7 @@ RRSetScreenConfig root: WINDOW subpixelOrder: SUBPIXELORDER - Errors: BadValue, BadMatch + Errors: Value, Match If the timestamp in this request is less than the time when the configuration was last successfully set, the request is @@ -209,8 +228,8 @@ RRSetScreenConfig 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 + Value errors are generated if the rotation is not an + allowed rotation. Value errors are generated, if, when the timestamps would allow the operation to succeed, or size-index are not possible (out of range). @@ -241,7 +260,7 @@ RRGetScreenInfo rates: LISTofCARD16 } - Errors: BadWindow + Errors: Window This event is delivered to clients selecting for notification with RRSelectInput requests using a RRScreenChangeNotifyMask. @@ -286,6 +305,25 @@ RRGetScreenInfo via a RRScreenChangeNotify event, so that they can adapt to screen size changes. +7.1. Extension Requests added in version 1.1 of the extension + +RRGetScreenSizeRange + drawable: DRAWABLE + + -> + + CARD16 minWidth, minHeight + CARD16 maxWidth, maxHeight + + Errors: Drawable + + Returns the range of possible screen sizes. The screen may be set to + any size within this range. + +RRSetScreenSize + drawable: DRAWABLE + timestamp: TIMESTAMP + config-timestamp: TIMESTAMP 8. Extension Events -- cgit v1.2.1 From 2370c88074c63bbe8d37d510e7e1f5c28fe6e573 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sat, 24 Jun 2006 16:22:44 -0700 Subject: Reformat license text, add Intel copyright --- COPYING | 49 +++++++++++++++---------------------------------- ChangeLog | 4 ---- protocol.txt | 2 +- randr.h | 35 ++++++++++++++++++----------------- randrproto.h | 31 ++++++++++++++++--------------- 5 files changed, 50 insertions(+), 71 deletions(-) delete mode 100644 ChangeLog diff --git a/COPYING b/COPYING index ac19ad6..252d1be 100644 --- a/COPYING +++ b/COPYING @@ -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 - - * configure.ac: - Update package version number for final X11R7 release candidate. diff --git a/protocol.txt b/protocol.txt index 282f60f..7dbfd2a 100644 --- a/protocol.txt +++ b/protocol.txt @@ -24,7 +24,7 @@ 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 XFree86 implementationhas been removed from the +document and in the XFree86 implementation has been removed from the protocol described here, as it has been overtaken by events. These events include: diff --git a/randr.h b/randr.h index 864ddd4..5be0a3b 100644 --- a/randr.h +++ b/randr.h @@ -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_ diff --git a/randrproto.h b/randrproto.h index 04d62fc..bfa3976 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 */ -- cgit v1.2.1 From 2907236309d2862f61dcb0c032df1abdb9adc80e Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sat, 24 Jun 2006 16:58:16 -0700 Subject: Clean up really broken text in the spec --- protocol.txt | 131 ++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 72 insertions(+), 59 deletions(-) diff --git a/protocol.txt b/protocol.txt index 7dbfd2a..d8b24c7 100644 --- a/protocol.txt +++ b/protocol.txt @@ -24,7 +24,7 @@ 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 XFree86 implementation has been removed from the +document and in the implementation has been removed from the protocol described here, as it has been overtaken by events. These events include: @@ -42,17 +42,16 @@ 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. +Rather than further delaying RandR's widespread deployment for a feature +long wanted by the community (resizing of screens, particularly on laptops), +or the deployment of a protocol design that might be flawed due to lack of +implementation experience, we decided to remove depth switching from the +protocol. It may be implementated at a later time if resources and +interests permit as a revision to the protocol described here, which will +remain a stable base for applications. The protocol described here has been +implemented in the main X.org server, and more fully in the hw/kdrive +implementation in the distribution, which fully implements resizing, +rotation and reflection. 1.2 Introduction to version 1.2 of the extension @@ -76,7 +75,15 @@ Additional requests and events are provided for this new functionality. 2. Acknowlegements -Our thanks to the contributors to the design found on the xpert mailing list. +Our thanks to the contributors to the design found on the xpert mailing +list, in particular: + +Alan Hourihane for work on the early implementation +Andrew C. Aitchison for help with the XFree86 DDX implementation +Andy Ritger for early questions about how mergefb/Xinerama work with RandR +Carl Worth for editing the specification and Usenix paper +David Dawes for XFree86 DDX integration work +Thomas Winischhofer for the hardware-accelerated SiS rotation implementation 2. Screen change model @@ -180,12 +187,12 @@ RRSelectInput Errors: Window, Value - 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. + 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 when + this request executes if the screen configuration has changed since + the client connected, to avoid race conditions. RRSetScreenConfig drawable: DRAWABLE @@ -243,7 +250,6 @@ RRGetScreenInfo root: WINDOW timestamp: TIMESTAMP config-timestamp: TIMESTAMP - nSizes: CARD16 sizeID: SIZEID rotation: ROTATION rate: CARD16 @@ -262,50 +268,47 @@ RRGetScreenInfo Errors: Window - 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. + RRGetScreenInfo returns information about the current and available + configurations for the screen associated with 'window'. - This call returns the root window of the screen which has changed. + 'rotations' contains the set of rotations and reflections supported + by the screen. - 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 + '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. 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. + in the face of race conditions. - Rate is the current refresh rate. This is zero when the refresh + 'timestamp' indicates when the configuration was last set. + + 'sizeID' 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 provide both the linear physical size - of the screen and the pixel size. + 'sizes' is the list of possible frame buffer sizes (at the normal + orientation. Each size indicates both the linear physical size of + the screen and the pixel size. - Refresh is the list of refresh rates for each size, each element - of sizes has a cooresponding element in refresh. An empty list + '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. + list. - Toolkits SHOULD use RRScreenChangeSelectInput to be notified - via a RRScreenChangeNotify event, so that they can adapt to - screen size changes. +7.1. Extension Requests added in version 1.2 of the extension -7.1. Extension Requests added in version 1.1 of the extension +As introduced above, version 1.2 of the extension splits the screen size +from the monitor configuration, permitting the subset of the screen +presented by multiple monitors to be configured. As a separate notion, the +size of the screen itself may be arbitrarily configured within a defined +range. RRGetScreenSizeRange drawable: DRAWABLE @@ -324,6 +327,18 @@ RRSetScreenSize drawable: DRAWABLE timestamp: TIMESTAMP config-timestamp: TIMESTAMP + width: CARD16 + height: CARD16 + + Errors: Drawable, Match, Value + + Sets the screen to the specified size. 'width' and 'height' must be + within the range allowed by GetScreenSizeRanges, otherwise a Value + error results. All active monitors must be configured to display a + subset of the specified size, else a Match error results. + +RRGetMonitorInfo + 8. Extension Events @@ -351,13 +366,12 @@ RRScreenChangeNotify 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 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. 'sizeID' 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 @@ -366,8 +380,7 @@ RRScreenChangeNotify 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. + organizations. Clients which select screen change notification events may be sent an event immediately if the screen configuration was @@ -377,7 +390,6 @@ RRScreenChangeNotify 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 @@ -403,6 +415,8 @@ list of what each version before 1.0 implemented: 1.1: Added refresh rates + 1.2: Separate out screens from monitors + Compatibility between 0.0 and 1.0 was *NOT* preserved, and 0.0 clients will fail against 1.0 servers. The wire encoding op-codes were changed for GetScreenInfo to ensure this failure in a relatively @@ -410,7 +424,6 @@ 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 -- cgit v1.2.1 From 3b72072c31258d1f12b93eba77b5e30cf46c5309 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sat, 24 Jun 2006 17:35:35 -0700 Subject: Repair broken parts of spec. Add RRGetMonitorInfo and RRSetMonitorConfig --- protocol.txt | 222 ++++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 176 insertions(+), 46 deletions(-) diff --git a/protocol.txt b/protocol.txt index d8b24c7..6ec3e92 100644 --- a/protocol.txt +++ b/protocol.txt @@ -141,13 +141,18 @@ There are no new error types defined by this extension. 5. Protocol Types +RRCONFIGSTATUS { + Success + InvalidConfigTime + InvalidTime + Failed } ROTATION { - RR_rotate_0 - RR_rotate_90 - RR_rotate_180 - RR_rotate_270 - RR-Reflect_X - RR_Reflect_Y } + Rotate_0 + Rotate_90 + Rotate_180 + Rotate_270 + Reflect_X + Reflect_Y } RRSELECTMASK { RRScreenChangeNotifyMask } @@ -160,6 +165,13 @@ SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render SubPixelVerticalBGR SubPixelNone } +SCREENSIZE { + widthInPixels, heightInPixels: CARD16 + widthInMillimeters, heightInMillimeters: CARD16 } + +REFRESH { + rates: LISTofCARD16 } + 6. Extension Initialization The name of this extension is "RANDR". @@ -204,6 +216,7 @@ RRSetScreenConfig -> + status: RRCONFIGSTATUS new-timestamp: TIMESTAMP config-timestamp: TIMESTAMP root: WINDOW @@ -211,35 +224,45 @@ RRSetScreenConfig Errors: Value, Match - 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 '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. - If rate is zero, the server selects an appropriate rate. + When this request succeeds, 'status' contains Success and the + requested changes to configuration will have been made. + + 'new-time-stamp' contains the time at which this request was + executed. + + 'config-timestamp' contains the time when the possible screen + configurations were last changed. + + 'root' contains the root window for the screen indicated by the + drawable. - 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. - - Value errors are generated if the rotation is not an - allowed rotation. Value errors are generated, if, when the - timestamps would allow the operation to succeed, or size-index - are not possible (out of range). + 'subpixelOrder' contains the resulting subpixel order of the screen + to allow correct subpixel rendering. + Value errors are generated when 'rotation', 'rate' or 'sizeID' are + invalid. RRGetScreenInfo window: WINDOW @@ -258,14 +281,6 @@ RRGetScreenInfo where: - SCREENSIZE { - widthInPixels, heightInPixels: CARD16 - widthInMillimeters, heightInMillimeters: CARD16 } - - REFRESH { - rates: LISTofCARD16 - } - Errors: Window RRGetScreenInfo returns information about the current and available @@ -338,7 +353,122 @@ RRSetScreenSize subset of the specified size, else a Match error results. RRGetMonitorInfo + drawable: DRAWABLE + + -> + + root: WINDOW + monitors: LISTofMONITOR + + where: + + MONITOR { + name: STRING + timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + x, y: INT16 + sizeID: SIZEID or Disabled + rotation: ROTATION + rate: CARD16 + rotations: SETofROTATION + defaultSizeID: SIZEID or Disabled + sizes: LISTofSCREENSIZE + refresh: LISTofREFRESH + } + + Errors: Drawable + + RRGetMonitorInfo returns information about the current and available + configurations for all monitors connected to the screen associated + with 'window'. + + 'root' is the root window of the screen. + + 'timestamp' indicates when the configuration was last set. + + 'config-timestamp' indicates when the screen configuration + information last changed: requests to set the screen will fail + unless the timestamp indicates that the information the client + is using is up to date, to ensure clients can be well behaved + in the face of race conditions. + + 'x' and 'y' indicate the position of this monitor within the screen + region. They will be set to 0 when the monitor is disabled. + + 'sizeID' indicates which size is active, or 'Disabled' indicating + that the monitor has been disabled and is not displaying the screen + contents. + + 'rotation' indicates the active rotation. It is set to Rotate_0 + when the monitor is disabled. + 'rate' is the current refresh rate. This is zero when monitor is + disabled, when the refresh rate is unknown or on devices for which + refresh is not relevant. + + 'rotations' contains the set of rotations and reflections supported + by the monitor. + + 'defaultSizeID' is the size the monitor is set to at server reset + time. + + 'sizes' is the list of possible displayed sizes (with rotation set + to Rotate_0). Each size indicates both the linear physical size of + the monitor and the pixel size of the displayed area. + + 'refresh' is the list of refresh rates for each size. Each element + of 'sizes' has a cooresponding element in 'refresh'. An empty list + indicates no known rates, or a device for which refresh is not + relevant. + +RRSetMonitorConfig + drawable: DRAWABLE + monitor: CARD32 + timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + x,y: INT16 + sizeID: SIZEID + rotation: ROTATION + rate: CARD16 + + -> + + status: RRStatus + new-timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + root: WINDOW + subpixelOrder: SUBPIXELORDER + + Errors: Drawable, Value, Match + + 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. + + Value errors are generated if the rotation is not an + allowed rotation. Value errors are generated, if, when the + timestamps would allow the operation to succeed, or size-index + are not possible (out of range). 8. Extension Events @@ -436,12 +566,12 @@ 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 + 0x0001 Rotate_0 + 0x0002 Rotate_90 + 0x0004 Rotate_180 + 0x0008 Rotate_270 + 0x0010 Reflect_X + 0x0020 Reflect_Y SETofRRSELECTMASK -- cgit v1.2.1 From 66cb6d24ecd161c9f0b42ba55d8ae642fe02729e Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sun, 25 Jun 2006 03:10:20 +0200 Subject: Add RRMonitorChangeNotify event. Complete RRSetMonitorConfig. --- protocol.txt | 161 ++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 122 insertions(+), 39 deletions(-) diff --git a/protocol.txt b/protocol.txt index 6ec3e92..1289f69 100644 --- a/protocol.txt +++ b/protocol.txt @@ -154,10 +154,13 @@ ROTATION { Reflect_X Reflect_Y } -RRSELECTMASK { RRScreenChangeNotifyMask } +RRSELECTMASK { RRScreenChangeNotifyMask + RRMonitorChangeNotifyMask (New in version 1.2) } SIZEID { CARD16 } +MONITOR { CARD32 } + SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render SubPixelHorizontalRGB extensions definitions; they are here SubPixelHorizontalBGR only for convenience. @@ -200,12 +203,20 @@ RRSelectInput Errors: Window, Value If 'enable' is RRScreenChangeNotifyMask, RRScreenChangeNotify events - will be sent anytime the screen configuration changes, either from + will be sent when the screen configuration changes, either from this protocol extension, or due to detected external screen configuration changes. RRScreenChangeNotify may also be sent when this request executes if the screen configuration has changed since the client connected, to avoid race conditions. + New for version 1.2 - if 'enable' contains RRMonitorChangeMask, + RRMonitorChangeNotify events will be sent when a the configuration + for a monitor associated with the screen changes, either through + this protocol extension or due to detected external monitor changes. + RRMonitorChangeNotify may also be sent when this request executes if + the monitor configuration has changed since the client connected, to + avoid race conditions. + RRSetScreenConfig drawable: DRAWABLE timestamp: TIMESTAMP @@ -423,52 +434,79 @@ RRGetMonitorInfo RRSetMonitorConfig drawable: DRAWABLE - monitor: CARD32 + monitorID: MONITOR timestamp: TIMESTAMP config-timestamp: TIMESTAMP - x,y: INT16 + x, y: INT16 sizeID: SIZEID rotation: ROTATION rate: CARD16 -> - status: RRStatus + status: RRCONFIGSTATUS new-timestamp: TIMESTAMP config-timestamp: TIMESTAMP root: WINDOW subpixelOrder: SUBPIXELORDER - Errors: Drawable, Value, Match - - 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. - - Value errors are generated if the rotation is not an - allowed rotation. Value errors are generated, if, when the - timestamps would allow the operation to succeed, or size-index - are not possible (out of range). + 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. + + 'sizeID' contains the index of desired size or Disabled indicating + the monitor should be disabled. 'sizeID' must be either a valid size + index or 'Disabled', else a Value error results. + + 'rotation' contains the desired rotation along with which + reflections should be enabled. The rotation and reflection values + must be among those allowed for this monitor, else a Value error + results. + + 'rate' contains the desired refresh rate. If it is zero, the server + selects an appropriate rate. Otherwise, the rate must be valid for + the selected size, else a Value error results. + + This request may fail for other indeterminate reasons, in which case + 'status' will be set to Failed and no configuration change will be + made. + + This request sets the monitor to the specified position size, rate, + rotation and reflection. The entire area of the monitor must fit + within the screen size, else a Match error results. As an example, + rotating the screen so that a single monitor fills the entire screen + before and after may necessitate disabling the monitor, resizing the + screen, then re-enabling the monitor at the new configuration to + avoid an invalid intermediate configuration. + + When this request succeeds, 'status' contains Success and the + requested changes to configuration will have been made. + + 'new-time-stamp' contains the time at which this request was + executed. + + 'config-timestamp' contains the time when the possible screen + configurations were last changed. + + 'root' contains the root window for the screen indicated by the + drawable. + + 'subpixelOrder' contains the resulting subpixel order of the monitor + to allow correct subpixel rendering. 8. Extension Events @@ -491,10 +529,10 @@ RRScreenChangeNotify window: WINDOW window requesting notification sizeID: SIZEID new ID of size subpixelOrder: SUBPIXELORDER order of subpixels - widthInPixels: INT16 - heightInPixels: INT16 - widthInMillimeters: INT16 - heightInMillimeters: INT16 + 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 @@ -520,6 +558,46 @@ RRScreenChangeNotify just at the time when a display manager or log in script might be changing the screen size or configuration. +8.1 Events added in version 1.2 of the RandR extension + +RRMonitorChangeNotify + + rotation: ROTATION; new rotation + sequenceNumber: CARD16 low 16 bits of request's seq. number + timestamp: TIMESTAMP time monitor was changed + configTimestamp: TIMESTAMP time config data was changed + root: WINDOW root window of screen + window: WINDOW window requesting notification + monitorID: MONITOR monitor which changed + sizeID: SIZEID ID of new size + subpixelOrder: SUBPIXELORDER order of subpixels + x: INT16 x position of monitor within screen + y: INT16 y position of monitor within screen + + This event is generated whenever the monitor configuration is changed + and sent to requesting clients. 'timestamp' indicates when the + monitor configuration was changed. 'configTimestamp' says when the + last time the configuration was changed. 'root' is the root of the + screen the change occurred on, 'window' is window selecting for this + event. 'sizeID' contains the index of the current size. + + This event is sent whenever the monitor's configuration changes + or if a new monitor configuration becomes available that was + not available in the past. In this case (config-timestamp in + the event not being equal to the config-timestamp returned in + the last call to RRGetMonitorInfo), the client MUST call + RRGetMonitorInfo to update its view of possible monitor + configurations to have a correct view of possible monitor + organizations. + + Clients which select monitor change notification events may be + sent an event immediately if the monitor configuration was + changed between when they connected to the X server and + selected for notification. This is to prevent a common race + that might occur on log-in, where many applications start up + just at the time when a display manager or log in script might + be changing the monitor size or configuration. + 9. Extension Versioning The RandR extension was developed in parallel with the implementation @@ -554,6 +632,11 @@ graceful way. Version 1.1 servers and clients are cross compatible with 1.0. Version 1.1 is considered to be stable and we intend upward compatibility from this point. +10. Relationship between RandR, XFree86-VidModeExtension and Xinerama + +Two other extensions have a direct relationship with this extension. This +section attempts to explain how these three are supposed to work together. + Appendix A. Protocol Encoding Syntactic Conventions -- cgit v1.2.1 From bb97699dcd1e274a1abc20f1a818aaf53b269a1b Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sun, 25 Jun 2006 03:25:59 +0200 Subject: Describe relationship between RandR, Xinerama and XFree86-VidModeExtension --- protocol.txt | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/protocol.txt b/protocol.txt index 1289f69..a89c79f 100644 --- a/protocol.txt +++ b/protocol.txt @@ -632,11 +632,43 @@ graceful way. Version 1.1 servers and clients are cross compatible with 1.0. Version 1.1 is considered to be stable and we intend upward compatibility from this point. -10. Relationship between RandR, XFree86-VidModeExtension and Xinerama +10. Relationship with other extensions Two other extensions have a direct relationship with this extension. This section attempts to explain how these three are supposed to work together. +10.1 XFree86-VidModeExtension + +XFree86-VidModeExtension changes the configuration of a single monitor +attached to the screen without changing the configuration of the screen +itself. It provides the ability to specify new mode lines for the server to +use along with selecting among existing mode lines. As it uses screen +numbers instead of window identifiers, it can be used to affect multiple +monitors in a single-screen Xinerama configuration. However, the association +between screen numbers and root windows in a multi-Screen environment is not +defined by the extension. Version 2.0 of this extension added the ability to +adjust the DAC values in a TrueColor server to modify the brightness curves +of the display. + +Most of the utility of this extension is subsumed by RandR version 1.2, with +the noted exception of specifying new mode lines and the gamma adjustments. +If these features continue to be useful, either some relationship between +the screen indices used in the XFree86-VidModeExtension and the +screen/monitor pairs used int RandR or an incorporation of this +functionality into RandR might be needed. + +10.2 Xinerama + +Xinerama provides a mechanism for describing the relationship between the +overall screen display and monitors placed within that area. As such, it +provides the query functionality of RandR 1.2 without any of the +configuration functionality. Applications using Xinerama to discover +monitor geometry can continue to do so, with the caveat that they will not be +informed of changes when they occur. However, Xinerama configuration data +will be updated, so applications selecting for RandR notification and +re-querying the configuration with the Xinerama extension will get updated +information. + Appendix A. Protocol Encoding Syntactic Conventions -- cgit v1.2.1 From efde5d9569afef58317905ce30910f80cb3d01c8 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sun, 25 Jun 2006 03:35:24 +0200 Subject: Start specifying the encoding for 1.2 requests --- protocol.txt | 54 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 42 insertions(+), 12 deletions(-) diff --git a/protocol.txt b/protocol.txt index a89c79f..63929cd 100644 --- a/protocol.txt +++ b/protocol.txt @@ -338,7 +338,7 @@ range. RRGetScreenSizeRange drawable: DRAWABLE - + -> CARD16 minWidth, minHeight @@ -351,8 +351,6 @@ RRGetScreenSizeRange RRSetScreenSize drawable: DRAWABLE - timestamp: TIMESTAMP - config-timestamp: TIMESTAMP width: CARD16 height: CARD16 @@ -679,7 +677,7 @@ protocol encoding document. A.1 Common Types - SETofROTATION + ROTATION 0x0001 Rotate_0 0x0002 Rotate_90 @@ -689,10 +687,10 @@ A.1 Common Types 0x0020 Reflect_Y - SETofRRSELECTMASK - - 0x0001 RRScreenChangeNotifyMask + RRSELECTMASK + 0x0001 ScreenChangeNotifyMask + 0x0002 MonitorChangeNotifyMask Added in version 1.2 A.2 Protocol Requests @@ -729,10 +727,10 @@ errors if used in version 1.0. -> 1 1 Reply 1 CARD8 status - 0x0 RRSetConfigSuccess - 0x1 RRSetConfigInvalidConfigTime - 0x2 RRSetConfigInvalidTime - 0x3 RRSetConfigFailed + 0x0 Success + 0x1 InvalidConfigTime + 0x2 InvalidTime + 0x3 Failed 2 CARD16 sequence number 4 0 reply length 4 TIMESTAMP new timestamp @@ -785,7 +783,38 @@ errors if used in version 1.0. 2 CARD16 number of rates (n) 2n CARD16 rates -A.2 Protocol Event +A.2.1 Protocol Requests added with version 1.2 + + RRGetScreenSizeRange + + 1 CARD8 major opcode + 1 0x06 RandR opcode + 2 2 length + 4 DRAWABLE drawable + -> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 reply length + 2 CARD16 minWidth + 2 CARD16 minHeight + 2 CARD16 maxWidth + 2 CARD16 maxHeight + 4 unused + 4 unused + 4 unused + 4 unused + + RRSetScreenSize + + 1 CARD8 major opcode + 1 0x07 RandR opcode + 2 3 length + 4 DRAWABLE drawable + 2 CARD16 width + 2 CARD16 height + +A.3 Protocol Events RRScreenChangeNotify @@ -803,6 +832,7 @@ A.2 Protocol Event 2 CARD16 width in millimeters 2 CARD16 height in millimeters +A.3.1 Protocol Events added with version 1.2 Bibliography -- cgit v1.2.1 From 69f5562610a94cb7c67b5e8bcd7d1e3df53bbcad Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sun, 25 Jun 2006 08:51:27 +0200 Subject: Finish encodings for 1.2 additions. --- protocol.txt | 150 ++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 112 insertions(+), 38 deletions(-) diff --git a/protocol.txt b/protocol.txt index 63929cd..ff07f62 100644 --- a/protocol.txt +++ b/protocol.txt @@ -157,9 +157,9 @@ ROTATION { RRSELECTMASK { RRScreenChangeNotifyMask RRMonitorChangeNotifyMask (New in version 1.2) } -SIZEID { CARD16 } +SIZEID { CARD16 or Disabled } -MONITOR { CARD32 } +MONITOR { CARD16 } SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render SubPixelHorizontalRGB extensions definitions; they are here @@ -221,7 +221,7 @@ RRSetScreenConfig drawable: DRAWABLE timestamp: TIMESTAMP config-timestamp: TIMESTAMP - sizeID: SIZEID + size-id: SIZEID rotation: ROTATION rate: CARD16 @@ -272,8 +272,8 @@ RRSetScreenConfig 'subpixelOrder' contains the resulting subpixel order of the screen to allow correct subpixel rendering. - Value errors are generated when 'rotation', 'rate' or 'sizeID' are - invalid. + Value errors are generated when 'rotation', 'rate' or 'size-id' + are invalid. RRGetScreenInfo window: WINDOW @@ -284,7 +284,7 @@ RRGetScreenInfo root: WINDOW timestamp: TIMESTAMP config-timestamp: TIMESTAMP - sizeID: SIZEID + size-id: SIZEID rotation: ROTATION rate: CARD16 sizes: LISTofSCREENSIZE @@ -310,7 +310,7 @@ RRGetScreenInfo 'timestamp' indicates when the configuration was last set. - 'sizeID' indicates which size is active. + '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. @@ -367,20 +367,19 @@ RRGetMonitorInfo -> root: WINDOW - monitors: LISTofMONITOR + monitors: LISTofMONITORINFO where: - MONITOR { - name: STRING + MONITORINFO { timestamp: TIMESTAMP config-timestamp: TIMESTAMP x, y: INT16 - sizeID: SIZEID or Disabled + size-id: SIZEID or Disabled rotation: ROTATION rate: CARD16 rotations: SETofROTATION - defaultSizeID: SIZEID or Disabled + default-size-id: SIZEID or Disabled sizes: LISTofSCREENSIZE refresh: LISTofREFRESH } @@ -404,7 +403,7 @@ RRGetMonitorInfo 'x' and 'y' indicate the position of this monitor within the screen region. They will be set to 0 when the monitor is disabled. - 'sizeID' indicates which size is active, or 'Disabled' indicating + 'size-id' indicates which size is active, or 'Disabled' indicating that the monitor has been disabled and is not displaying the screen contents. @@ -418,8 +417,8 @@ RRGetMonitorInfo 'rotations' contains the set of rotations and reflections supported by the monitor. - 'defaultSizeID' is the size the monitor is set to at server reset - time. + 'default-size-id' is the size the monitor is set to at server + reset time. 'sizes' is the list of possible displayed sizes (with rotation set to Rotate_0). Each size indicates both the linear physical size of @@ -432,11 +431,11 @@ RRGetMonitorInfo RRSetMonitorConfig drawable: DRAWABLE - monitorID: MONITOR + monitor-index: MONITOR timestamp: TIMESTAMP config-timestamp: TIMESTAMP x, y: INT16 - sizeID: SIZEID + size-id: SIZEID rotation: ROTATION rate: CARD16 @@ -446,6 +445,7 @@ RRSetMonitorConfig new-timestamp: TIMESTAMP config-timestamp: TIMESTAMP root: WINDOW + monitor: MONITOR subpixelOrder: SUBPIXELORDER Errors: Value, Match @@ -466,9 +466,9 @@ RRSetMonitorConfig monitor's content. 'x' and 'y' must be within the screen size, else a Value error results. - 'sizeID' contains the index of desired size or Disabled indicating - the monitor should be disabled. 'sizeID' must be either a valid size - index or 'Disabled', else a Value error results. + 'size-id' contains the index of desired size or Disabled + indicating the monitor should be disabled. 'size-id' must be + either a valid size index or 'Disabled', else a Value error results. 'rotation' contains the desired rotation along with which reflections should be enabled. The rotation and reflection values @@ -525,7 +525,7 @@ RRScreenChangeNotify configTimestamp: TIMESTAMP time config data was changed root: WINDOW root window of screen window: WINDOW window requesting notification - sizeID: SIZEID new ID of size + size-id: SIZEID index of new size subpixelOrder: SUBPIXELORDER order of subpixels widthInPixels: CARD16 heightInPixels: CARD16 @@ -537,7 +537,7 @@ RRScreenChangeNotify 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. 'sizeID' contains the index of the current size. + 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 @@ -566,8 +566,8 @@ RRMonitorChangeNotify configTimestamp: TIMESTAMP time config data was changed root: WINDOW root window of screen window: WINDOW window requesting notification - monitorID: MONITOR monitor which changed - sizeID: SIZEID ID of new size + monitor-index: MONITOR monitor which changed + size-id: SIZEID new size index subpixelOrder: SUBPIXELORDER order of subpixels x: INT16 x position of monitor within screen y: INT16 y position of monitor within screen @@ -577,7 +577,7 @@ RRMonitorChangeNotify monitor configuration was changed. 'configTimestamp' says when the last time the configuration was changed. 'root' is the root of the screen the change occurred on, 'window' is window selecting for this - event. 'sizeID' contains the index of the current size. + event. 'size-id' contains the index of the current size. This event is sent whenever the monitor's configuration changes or if a new monitor configuration becomes available that was @@ -692,6 +692,16 @@ A.1 Common Types 0x0001 ScreenChangeNotifyMask 0x0002 MonitorChangeNotifyMask Added in version 1.2 + RRCONFIGSTATUS + + 0x0 Success + 0x1 InvalidConfigTime + 0x2 InvalidTime + 0x3 Failed + + SIZEID + 0xffff Disabled + A.2 Protocol Requests @@ -713,24 +723,22 @@ errors if used in version 1.0. 1 CARD32 major version 1 CARD32 minor version - RRSetScreenConfig + RRSetScreenConfig + 1 CARD8 major opcode 1 0x02 RandR opcode - 2 5 length + 2 6 length 4 DRAWABLE drawable on screen to be configured 4 TIMESTAMP timestamp - 2 SIZEID size id + 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 CARD8 status - 0x0 Success - 0x1 InvalidConfigTime - 0x2 InvalidTime - 0x3 Failed + 1 RRCONFIGSTATUS status 2 CARD16 sequence number 4 0 reply length 4 TIMESTAMP new timestamp @@ -740,7 +748,7 @@ errors if used in version 1.0. 2 CARD16 pad4 4 CARD32 pad5 4 CARD32 pad6 - + RRSelectInput @@ -766,14 +774,14 @@ errors if used in version 1.0. 4 WINDOW root window 4 TIMESTAMP timestamp 4 TIMESTAMP config timestamp - 2 CARD16 number of SIZE following - 2 SIZEID sizeID + 2 CARD16 number of SCREENSIZE following + 2 SIZEID current size index 2 ROTATION current rotation and reflection - 2 CARD16 rate (1.1) + 2 CARD16 current rate (added in version 1.1) 2 CARD16 length of rate info (number of CARD16s) 2 CARD16 pad - SIZE + SCREENSIZE 2 CARD16 width in pixels 2 CARD16 height in pixels 2 CARD16 width in millimeters @@ -805,6 +813,7 @@ A.2.1 Protocol Requests added with version 1.2 4 unused 4 unused + RRSetScreenSize 1 CARD8 major opcode @@ -814,6 +823,71 @@ A.2.1 Protocol Requests added with version 1.2 2 CARD16 width 2 CARD16 height + + RRGetMonitorInfo + + 1 CARD8 major opcode + 1 0x08 RandR opcode + 2 2 length + 4 DRAWABLE drawable + -> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 m*7 + s*2 + (r*2+p)/4 reply length + 4 WINDOW root + 2 CARD16 m = number of MONITORINFO following + 2 CARD16 s = number of SIZE following + 2 CARD16 r = number of CARD16 in rates following + 14 unused + m*28 LISTofMONITORINFO one per monitor + s*8 LISTofSCREENSIZE for all monitors + r*2 LISTofREFRESH refresh rates + p pad pad(r*2) + + MONITORINFO + 4 TIMESTAMP timestamp + 4 TIMESTAMP config-timestamp + 2 INT16 x + 2 INT16 y + 2 ROTATION rotation + 2 CARD16 rate + 2 SETofROTATION rotations + 2 SIZEID or Disabled default-size-id + 2 CARD16 start offset in LISTofSCREENSIZE + 2 CARD16 number of SCREENSIZE + 2 CARD16 CARD16 offset in LISTofREFRESH + 2 CARD16 number of CARD16 in refresh rates + + + RRSetMonitorConfig + + 1 CARD8 major opcode + 1 0x09 RandR opcode + 2 7 length + 4 DRAWABLE drawable + 4 TIMESTAMP timestamp + 4 TIMESTAMP config timestamp + 2 SIZEID size index + 2 ROTATION rotation/reflection + 2 CARD16 rate + 2 MONITOR monitor index + 2 INT16 x + 2 INT16 y + -> + 1 1 Reply + 1 RRCONFIGSTATUS status + 2 CARD16 sequence number + 4 0 reply length + 4 TIMESTAMP new timestamp + 4 TIMESTAMP new configuration timestamp + 4 WINDOW root + 2 SUBPIXELORDER subpixel order defined in Render + 2 MONITOR monitor + 4 CARD32 pad6 + 4 CARD32 pad7 + + A.3 Protocol Events RRScreenChangeNotify -- cgit v1.2.1 From d606ad207ccef5c050374b535acb0bd3ed3b95aa Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Mon, 26 Jun 2006 12:42:50 +0200 Subject: move protocol.txt to randrproto.txt. Start updating headers for version 1.2 --- Makefile.am | 2 +- protocol.txt | 919 -------------------------------------------------- randr.h | 43 ++- randrproto.h | 1 + randrproto.txt | 1023 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 1065 insertions(+), 923 deletions(-) delete mode 100644 protocol.txt create mode 100644 randrproto.txt diff --git a/Makefile.am b/Makefile.am index 62a5502..e741694 100644 --- a/Makefile.am +++ b/Makefile.am @@ -6,4 +6,4 @@ randr_HEADERS = \ pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = randrproto.pc -EXTRA_DIST = autogen.sh randrproto.pc.in +EXTRA_DIST = autogen.sh randrproto.pc.in randrproto.txt diff --git a/protocol.txt b/protocol.txt deleted file mode 100644 index ff07f62..0000000 --- a/protocol.txt +++ /dev/null @@ -1,919 +0,0 @@ - The X Resize, Rotate and Reflect Extension - Version 1.2 - 2006-4-13 - - Jim Gettys - Jim.Gettys@hp.com - Cambridge Research Laboratory - HP Labs - Hewlett Packard Company - - Keith Packard - keith.packard@intel.com - Open Source Technology Center - Intel Corporation - -1. Introduction - -The X Resize, Rotate and Reflect Extension, called RandR for short, -brings the ability to resize, rotate and reflect the root window of a -screen. It is based on the X Resize and Rotate Extension as specified -in the Proceedings of the 2001 Usenix Technical Conference [RANDR]. - -RandR as implemented and integrated into the X server differs in -one substantial fashion from the design discussed in that paper: that -is, RandR 1.0 does not implement the depth switching described in that -document, and the support described for that in the protocol in that -document and in the implementation has been removed from the -protocol described here, as it has been overtaken by events. - -These events include: - o Modern toolkits (in this case, GTK+ 2.x) have progressed to the point - of implementing migration between screens of arbitrary depths - o The continued advance of Moore's law has made limited amounts of VRAM - less of an issue, reducing the pressure to implement depth switching - on laptops or desktop systems - o The continued decline of legacy toolkits whose design would have - required depth switching to support migration - o The lack of depth switchin implementation experience in the - intervening time, due to events beyond our control - -Additionally, the requirement to support depth switching might -complicate other re-engineering of the device independent part of the -X server that is currently being contemplated. - -Rather than further delaying RandR's widespread deployment for a feature -long wanted by the community (resizing of screens, particularly on laptops), -or the deployment of a protocol design that might be flawed due to lack of -implementation experience, we decided to remove depth switching from the -protocol. It may be implementated at a later time if resources and -interests permit as a revision to the protocol described here, which will -remain a stable base for applications. The protocol described here has been -implemented in the main X.org server, and more fully in the hw/kdrive -implementation in the distribution, which fully implements resizing, -rotation and reflection. - -1.2 Introduction to version 1.2 of the extension - -One of the significant limitations found in version 1.1 of the RandR -protocol was the inability to deal with the Xinerama model where multiple -monitors display portions of a common underlying screen. In this environment, -the size of the 'porthole' shown by each monitor is independent of the -overall size of the screen, and the porthole may be located anywhere within -the screen. - -The effect is to decouple the reported size of the screen from the size -presented by each monitor, and to permit multiple monitors to present -information for a single screen. - -To extend RandR for this model, we separate out the monitor and screen -configuration information and permit them to be configured separately. For -compatibility with the 1.1 version of the protocol, we make the 1.1 requests -simultaneously affect both the screen and the (presumably sole) monitor. - -Additional requests and events are provided for this new functionality. - -2. Acknowlegements - -Our thanks to the contributors to the design found on the xpert mailing -list, in particular: - -Alan Hourihane for work on the early implementation -Andrew C. Aitchison for help with the XFree86 DDX implementation -Andy Ritger for early questions about how mergefb/Xinerama work with RandR -Carl Worth for editing the specification and Usenix paper -David Dawes for XFree86 DDX integration work -Thomas Winischhofer for the hardware-accelerated SiS rotation implementation - -2. Screen change model - -Screens may change dynamically, either under control of this -extension, or due to external events. Examples include: monitors being -swapped, you pressing a button to switch from internal display to an -external monitor on a laptop, or, eventually, the hotplug of a display -card entirely on busses such as Cardbus which permit hot-swap (which -will require other work in addition to this extension). - -Since the screen configuration is dynamic and asynchronous to the -client and may change at any time RandR provides mechanisms to ensure -that your clients view is up to date with the configuration -possibilities of the moment and enforces applications that wish to -control the configuration to prove that their information is up to -date before honoring requests to change the screen configuration (by -requiring a timestamp on the request). - -Interested applications are notified whenever the screen configuration -changes, providing the current size of the screen and subpixel order -(see the Render extension [RENDER]), to enabel proper rendering of -subpixel decimated client text to continue, along with a time stamp of -the configuration change. A client must refresh its knowledge of the -screen configuration before attempting to change the configuration -after a notification, or the request will fail. - -To avoid multiplicative explosion between orientation, reflection -and sizes, the sizes are only those sizes in the normal (0) rotation. - -Rotation and reflection and how they interact can be confusing. In -Randr, the coordinate system is rotated in a counter-clockwise -direction relative to the normal orientation. Reflection is along the -window system coordinate system, not the physical screen X and Y axis, -so that rotation and reflection do not interact. The other way to -consider reflection is to is specified in the "normal" orientation, -before rotation, if you find the other way confusing. - -We expect that most clients and toolkits will be oblivious to changes -to the screen stucture, as they generally use the values in the -connections Display structure directly. By toolkits updating the -values on the fly, we believe pop-up menus and other pop up windows -will position themselves correctly in the face of screen configuration -changes (the issue is ensuring that pop-ups are visible on the -reconfigured screen). - -3. Data Types - -The subpixel order is shared with the Render extension, and is -documented there. The only datatype defined is the screen size, -defined in the normal (0 degree) orientation. - -4. Errors - -There are no new error types defined by this extension. - -5. Protocol Types - -RRCONFIGSTATUS { - Success - InvalidConfigTime - InvalidTime - Failed } -ROTATION { - Rotate_0 - Rotate_90 - Rotate_180 - Rotate_270 - Reflect_X - Reflect_Y } - -RRSELECTMASK { RRScreenChangeNotifyMask - RRMonitorChangeNotifyMask (New in version 1.2) } - -SIZEID { CARD16 or Disabled } - -MONITOR { CARD16 } - -SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render - SubPixelHorizontalRGB extensions definitions; they are here - SubPixelHorizontalBGR only for convenience. - SubPixelVerticalRGB - SubPixelVerticalBGR - SubPixelNone } - -SCREENSIZE { - widthInPixels, heightInPixels: CARD16 - widthInMillimeters, heightInMillimeters: CARD16 } - -REFRESH { - rates: LISTofCARD16 } - -6. Extension Initialization - -The name of this extension is "RANDR". - -RRQueryVersion - client-major-version: CARD32 - client-minor-version: CARD32 - -> - major-version: CARD32 - minor-version: CARD32 - - The client sends the highest supported version to the server - and the server sends the highest version it supports, but no - higher than the requested version. Major versions changes can - introduce incompatibilities in existing functionality, minor - version changes introduce only backward compatible changes. - It is the clients responsibility to ensure that the server - supports a version which is compatible with its expectations. - -7. Extension Requests - -RRSelectInput - window: WINDOW - enable: SETofRRSELECTMASK - - Errors: Window, Value - - If 'enable' is RRScreenChangeNotifyMask, RRScreenChangeNotify events - will be sent when the screen configuration changes, either from - this protocol extension, or due to detected external screen - configuration changes. RRScreenChangeNotify may also be sent when - this request executes if the screen configuration has changed since - the client connected, to avoid race conditions. - - New for version 1.2 - if 'enable' contains RRMonitorChangeMask, - RRMonitorChangeNotify events will be sent when a the configuration - for a monitor associated with the screen changes, either through - this protocol extension or due to detected external monitor changes. - RRMonitorChangeNotify may also be sent when this request executes if - the monitor configuration has changed since the client connected, to - avoid race conditions. - -RRSetScreenConfig - drawable: DRAWABLE - timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - size-id: SIZEID - rotation: ROTATION - rate: CARD16 - - -> - - status: RRCONFIGSTATUS - new-timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - root: WINDOW - subpixelOrder: SUBPIXELORDER - - Errors: Value, Match - - If 'timestamp' is less than the time when the configuration was last - successfully set, the request is ignored and InvalidTime returned in - status. - - If 'config-timestamp' is not equal to when the server's screen - configurations last changed, the request is ignored and - InvalidConfigTime returned in status. This could occur if the - screen changed since you last made a RRGetScreenInfo request, - perhaps by a different piece of display hardware being installed. - Rather than allowing an incorrect call to be executed based on stale - data, the server will ignore the request. - - 'rate' contains the desired refresh rate. If it is zero, the server - selects an appropriate rate. - - This request may fail for other indeterminate reasons, in which case - 'status' will be set to Failed and no configuration change will be - made. - - This request sets the screen to the specified size, rate, rotation - and reflection. - - When this request succeeds, 'status' contains Success and the - requested changes to configuration will have been made. - - 'new-time-stamp' contains the time at which this request was - executed. - - 'config-timestamp' contains the time when the possible screen - configurations were last changed. - - 'root' contains the root window for the screen indicated by the - drawable. - - 'subpixelOrder' contains the resulting subpixel order of the screen - to allow correct subpixel rendering. - - Value errors are generated when 'rotation', 'rate' or 'size-id' - are invalid. - -RRGetScreenInfo - window: WINDOW - - -> - - rotations: SETofROTATION - root: WINDOW - timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - size-id: SIZEID - rotation: ROTATION - rate: CARD16 - sizes: LISTofSCREENSIZE - refresh: LISTofREFRESH - - where: - - Errors: Window - - RRGetScreenInfo returns information about the current and available - configurations for the screen associated with 'window'. - - 'rotations' contains the set of rotations and reflections supported - by the screen. - - 'root' is the root window of the screen. - - 'config-timestamp' indicates when the screen configuration - information last changed: requests to set the screen will fail - unless the timestamp indicates that the information the client - is using is up to date, to ensure clients can be well behaved - in the face of race conditions. - - 'timestamp' indicates when the configuration was last set. - - 'size-id' indicates which size is active. - - 'rate' is the current refresh rate. This is zero when the refresh - rate is unknown or on devices for which refresh is not relevant. - - 'sizes' is the list of possible frame buffer sizes (at the normal - orientation. Each size indicates both the linear physical size of - the screen and the pixel size. - - 'refresh' is the list of refresh rates for each size. Each element - of 'sizes' has a cooresponding element in 'refresh'. An empty list - indicates no known rates, or a device for which refresh is not - relevant. - - The default size of the screen (the size that would become the - current size when the server resets) is the first size in the - list. - -7.1. Extension Requests added in version 1.2 of the extension - -As introduced above, version 1.2 of the extension splits the screen size -from the monitor configuration, permitting the subset of the screen -presented by multiple monitors to be configured. As a separate notion, the -size of the screen itself may be arbitrarily configured within a defined -range. - -RRGetScreenSizeRange - drawable: DRAWABLE - - -> - - CARD16 minWidth, minHeight - CARD16 maxWidth, maxHeight - - Errors: Drawable - - Returns the range of possible screen sizes. The screen may be set to - any size within this range. - -RRSetScreenSize - drawable: DRAWABLE - width: CARD16 - height: CARD16 - - Errors: Drawable, Match, Value - - Sets the screen to the specified size. 'width' and 'height' must be - within the range allowed by GetScreenSizeRanges, otherwise a Value - error results. All active monitors must be configured to display a - subset of the specified size, else a Match error results. - -RRGetMonitorInfo - drawable: DRAWABLE - - -> - - root: WINDOW - monitors: LISTofMONITORINFO - - where: - - MONITORINFO { - timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - x, y: INT16 - size-id: SIZEID or Disabled - rotation: ROTATION - rate: CARD16 - rotations: SETofROTATION - default-size-id: SIZEID or Disabled - sizes: LISTofSCREENSIZE - refresh: LISTofREFRESH - } - - Errors: Drawable - - RRGetMonitorInfo returns information about the current and available - configurations for all monitors connected to the screen associated - with 'window'. - - 'root' is the root window of the screen. - - 'timestamp' indicates when the configuration was last set. - - 'config-timestamp' indicates when the screen configuration - information last changed: requests to set the screen will fail - unless the timestamp indicates that the information the client - is using is up to date, to ensure clients can be well behaved - in the face of race conditions. - - 'x' and 'y' indicate the position of this monitor within the screen - region. They will be set to 0 when the monitor is disabled. - - 'size-id' indicates which size is active, or 'Disabled' indicating - that the monitor has been disabled and is not displaying the screen - contents. - - 'rotation' indicates the active rotation. It is set to Rotate_0 - when the monitor is disabled. - - 'rate' is the current refresh rate. This is zero when monitor is - disabled, when the refresh rate is unknown or on devices for which - refresh is not relevant. - - 'rotations' contains the set of rotations and reflections supported - by the monitor. - - 'default-size-id' is the size the monitor is set to at server - reset time. - - 'sizes' is the list of possible displayed sizes (with rotation set - to Rotate_0). Each size indicates both the linear physical size of - the monitor and the pixel size of the displayed area. - - 'refresh' is the list of refresh rates for each size. Each element - of 'sizes' has a cooresponding element in 'refresh'. An empty list - indicates no known rates, or a device for which refresh is not - relevant. - -RRSetMonitorConfig - drawable: DRAWABLE - monitor-index: MONITOR - timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - x, y: INT16 - size-id: SIZEID - rotation: ROTATION - rate: CARD16 - - -> - - status: RRCONFIGSTATUS - new-timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - root: WINDOW - monitor: MONITOR - subpixelOrder: SUBPIXELORDER - - Errors: Value, Match - - If 'timestamp' is less than the time when the configuration was last - successfully set, the request is ignored and InvalidTime returned in - status. - - If 'config-timestamp' is not equal to when the monitor's - configuration last changed, the request is ignored and - InvalidConfigTime returned in status. This could occur if the - monitor changed since you last made a RRGetScreenInfo request, - perhaps by a different monitor being connected to the machine. - Rather than allowing an incorrect call to be executed based on stale - data, the server will ignore the request. - - 'x' and 'y' contain the desired location within the screen for this - monitor's content. 'x' and 'y' must be within the screen size, else - a Value error results. - - 'size-id' contains the index of desired size or Disabled - indicating the monitor should be disabled. 'size-id' must be - either a valid size index or 'Disabled', else a Value error results. - - 'rotation' contains the desired rotation along with which - reflections should be enabled. The rotation and reflection values - must be among those allowed for this monitor, else a Value error - results. - - 'rate' contains the desired refresh rate. If it is zero, the server - selects an appropriate rate. Otherwise, the rate must be valid for - the selected size, else a Value error results. - - This request may fail for other indeterminate reasons, in which case - 'status' will be set to Failed and no configuration change will be - made. - - This request sets the monitor to the specified position size, rate, - rotation and reflection. The entire area of the monitor must fit - within the screen size, else a Match error results. As an example, - rotating the screen so that a single monitor fills the entire screen - before and after may necessitate disabling the monitor, resizing the - screen, then re-enabling the monitor at the new configuration to - avoid an invalid intermediate configuration. - - When this request succeeds, 'status' contains Success and the - requested changes to configuration will have been made. - - 'new-time-stamp' contains the time at which this request was - executed. - - 'config-timestamp' contains the time when the possible screen - configurations were last changed. - - 'root' contains the root window for the screen indicated by the - drawable. - - 'subpixelOrder' contains the resulting subpixel order of the monitor - to allow correct subpixel rendering. - -8. Extension Events - -Clients MAY select for ConfigureNotify on the root window to be -informed of screen changes. This may be advantageous if all your -clients need to know is the size of the root window, as it avoids -round trips to set up the extension. - -RRScreenChangeNotify is sent if RRSelectInput has requested it -whenever properties of the screen change, which may be due to external -factors, such as recabling a monitor, etc. - -RRScreenChangeNotify - - rotation: ROTATION; new rotation - sequenceNumber: CARD16 low 16 bits of request's seq. number - timestamp: TIMESTAMP time screen was changed - configTimestamp: TIMESTAMP time config data was changed - root: WINDOW root window of screen - window: WINDOW window requesting notification - size-id: SIZEID index of new size - subpixelOrder: SUBPIXELORDER order of subpixels - widthInPixels: CARD16 - heightInPixels: CARD16 - widthInMillimeters: CARD16 - heightInMillimeters: CARD16 - - This event is generated whenever the screen configuration is changed - and sent to requesting clients. 'timestamp' indicates when the - screen configuration was changed. 'configTimestamp' says when the - last time the configuration was changed. 'root' is the root of the - screen the change occurred on, 'window' is window selecting for this - event. 'size-id' contains the index of the current size. - - This event is sent whenever the screen's configuration changes - or if a new screen configuration becomes available that was - not available in the past. In this case (config-timestamp in - the event not being equal to the config-timestamp returned in - the last call to RRGetScreenInfo), the client MUST call - RRGetScreenInfo to update its view of possible screen - configurations to have a correct view of possible screen - organizations. - - Clients which select screen change notification events may be - sent an event immediately if the screen configuration was - changed between when they connected to the X server and - selected for notification. This is to prevent a common race - that might occur on log-in, where many applications start up - just at the time when a display manager or log in script might - be changing the screen size or configuration. - -8.1 Events added in version 1.2 of the RandR extension - -RRMonitorChangeNotify - - rotation: ROTATION; new rotation - sequenceNumber: CARD16 low 16 bits of request's seq. number - timestamp: TIMESTAMP time monitor was changed - configTimestamp: TIMESTAMP time config data was changed - root: WINDOW root window of screen - window: WINDOW window requesting notification - monitor-index: MONITOR monitor which changed - size-id: SIZEID new size index - subpixelOrder: SUBPIXELORDER order of subpixels - x: INT16 x position of monitor within screen - y: INT16 y position of monitor within screen - - This event is generated whenever the monitor configuration is changed - and sent to requesting clients. 'timestamp' indicates when the - monitor configuration was changed. 'configTimestamp' says when the - last time the configuration was changed. 'root' is the root of the - screen the change occurred on, 'window' is window selecting for this - event. 'size-id' contains the index of the current size. - - This event is sent whenever the monitor's configuration changes - or if a new monitor configuration becomes available that was - not available in the past. In this case (config-timestamp in - the event not being equal to the config-timestamp returned in - the last call to RRGetMonitorInfo), the client MUST call - RRGetMonitorInfo to update its view of possible monitor - configurations to have a correct view of possible monitor - organizations. - - Clients which select monitor change notification events may be - sent an event immediately if the monitor configuration was - changed between when they connected to the X server and - selected for notification. This is to prevent a common race - that might occur on log-in, where many applications start up - just at the time when a display manager or log in script might - be changing the monitor size or configuration. - -9. Extension Versioning - -The RandR extension was developed in parallel with the implementation -to ensure the feasibility of various portions of the design. As -portions of the extension are implemented, the version number of the -extension has changed to reflect the portions of the standard provied. -This document describes the version 1.0 of the specification, the -partial implementations have version numbers less than that. Here's a -list of what each version before 1.0 implemented: - - 0.0: This prototype implemented resize and rotation in the - TinyX server Used approximately the protocol described in - the Usenix paper. Appeared in the TinyX server in - XFree86 4.2, but not in the XFree86 main server. - - 0.1: Added subpixel order, added an event for subpixel order. - This version was never checked in to XFree86 CVS. - - 1.0: Implements resize, rotation, and reflection. Implemented - both in the XFree86 main server (size change only at this - date), and fully (size change, rotation, and reflection) - in XFree86's TinyX server. - - 1.1: Added refresh rates - - 1.2: Separate out screens from monitors - -Compatibility between 0.0 and 1.0 was *NOT* preserved, and 0.0 clients -will fail against 1.0 servers. The wire encoding op-codes were -changed for GetScreenInfo to ensure this failure in a relatively -graceful way. Version 1.1 servers and clients are cross compatible with -1.0. Version 1.1 is considered to be stable and we intend upward -compatibility from this point. - -10. Relationship with other extensions - -Two other extensions have a direct relationship with this extension. This -section attempts to explain how these three are supposed to work together. - -10.1 XFree86-VidModeExtension - -XFree86-VidModeExtension changes the configuration of a single monitor -attached to the screen without changing the configuration of the screen -itself. It provides the ability to specify new mode lines for the server to -use along with selecting among existing mode lines. As it uses screen -numbers instead of window identifiers, it can be used to affect multiple -monitors in a single-screen Xinerama configuration. However, the association -between screen numbers and root windows in a multi-Screen environment is not -defined by the extension. Version 2.0 of this extension added the ability to -adjust the DAC values in a TrueColor server to modify the brightness curves -of the display. - -Most of the utility of this extension is subsumed by RandR version 1.2, with -the noted exception of specifying new mode lines and the gamma adjustments. -If these features continue to be useful, either some relationship between -the screen indices used in the XFree86-VidModeExtension and the -screen/monitor pairs used int RandR or an incorporation of this -functionality into RandR might be needed. - -10.2 Xinerama - -Xinerama provides a mechanism for describing the relationship between the -overall screen display and monitors placed within that area. As such, it -provides the query functionality of RandR 1.2 without any of the -configuration functionality. Applications using Xinerama to discover -monitor geometry can continue to do so, with the caveat that they will not be -informed of changes when they occur. However, Xinerama configuration data -will be updated, so applications selecting for RandR notification and -re-querying the configuration with the Xinerama extension will get updated -information. - -Appendix A. Protocol Encoding - -Syntactic Conventions - -This document uses the same syntactic conventions as the core X -protocol encoding document. - - -A.1 Common Types - - ROTATION - - 0x0001 Rotate_0 - 0x0002 Rotate_90 - 0x0004 Rotate_180 - 0x0008 Rotate_270 - 0x0010 Reflect_X - 0x0020 Reflect_Y - - - RRSELECTMASK - - 0x0001 ScreenChangeNotifyMask - 0x0002 MonitorChangeNotifyMask Added in version 1.2 - - RRCONFIGSTATUS - - 0x0 Success - 0x1 InvalidConfigTime - 0x2 InvalidTime - 0x3 Failed - - SIZEID - 0xffff Disabled - -A.2 Protocol Requests - - -Opcodes 0x1 and 0x3 were used in the 0.0 protocols, and will return -errors if used in version 1.0. - - RRQueryVersion - - 1 CARD8 major opcode - 1 0x01 RandR opcode - 2 3 length - 4 CARD32 major version - 4 CARD32 minor version - -> - 1 1 Reply - 1 unused - 2 CARD16 sequence number - 4 0 reply length - 1 CARD32 major version - 1 CARD32 minor version - - - RRSetScreenConfig - - 1 CARD8 major opcode - 1 0x02 RandR opcode - 2 6 length - 4 DRAWABLE drawable on screen to be configured - 4 TIMESTAMP timestamp - 4 TIMESTAMP config timestamp - 2 SIZEID size index - 2 ROTATION rotation/reflection - 2 CARD16 refresh rate (1.1 only) - 2 CARD16 pad - -> - 1 1 Reply - 1 RRCONFIGSTATUS status - 2 CARD16 sequence number - 4 0 reply length - 4 TIMESTAMP new timestamp - 4 TIMESTAMP new configuration timestamp - 4 WINDOW root - 2 SUBPIXELORDER subpixel order defined in Render - 2 CARD16 pad4 - 4 CARD32 pad5 - 4 CARD32 pad6 - - - RRSelectInput - - 1 CARD8 major opcode - 1 0x04 RandR opcode - 2 3 length - 4 WINDOW window - 2 SETofRRSELECTMASK enable - 2 CARD16 pad - - - RRGetScreenInfo - - 1 CARD8 major opcode - 1 0x05 RandR opcode - 2 2 length - 4 WINDOW window - -> - 1 1 Reply - 1 CARD8 set of Rotations - 2 CARD16 sequence number - 4 0 reply length - 4 WINDOW root window - 4 TIMESTAMP timestamp - 4 TIMESTAMP config timestamp - 2 CARD16 number of SCREENSIZE following - 2 SIZEID current size index - 2 ROTATION current rotation and reflection - 2 CARD16 current rate (added in version 1.1) - 2 CARD16 length of rate info (number of CARD16s) - 2 CARD16 pad - - SCREENSIZE - 2 CARD16 width in pixels - 2 CARD16 height in pixels - 2 CARD16 width in millimeters - 2 CARD16 height in millimeters - - REFRESH - 2 CARD16 number of rates (n) - 2n CARD16 rates - -A.2.1 Protocol Requests added with version 1.2 - - RRGetScreenSizeRange - - 1 CARD8 major opcode - 1 0x06 RandR opcode - 2 2 length - 4 DRAWABLE drawable - -> - 1 1 Reply - 1 unused - 2 CARD16 sequence number - 4 0 reply length - 2 CARD16 minWidth - 2 CARD16 minHeight - 2 CARD16 maxWidth - 2 CARD16 maxHeight - 4 unused - 4 unused - 4 unused - 4 unused - - - RRSetScreenSize - - 1 CARD8 major opcode - 1 0x07 RandR opcode - 2 3 length - 4 DRAWABLE drawable - 2 CARD16 width - 2 CARD16 height - - - RRGetMonitorInfo - - 1 CARD8 major opcode - 1 0x08 RandR opcode - 2 2 length - 4 DRAWABLE drawable - -> - 1 1 Reply - 1 unused - 2 CARD16 sequence number - 4 m*7 + s*2 + (r*2+p)/4 reply length - 4 WINDOW root - 2 CARD16 m = number of MONITORINFO following - 2 CARD16 s = number of SIZE following - 2 CARD16 r = number of CARD16 in rates following - 14 unused - m*28 LISTofMONITORINFO one per monitor - s*8 LISTofSCREENSIZE for all monitors - r*2 LISTofREFRESH refresh rates - p pad pad(r*2) - - MONITORINFO - 4 TIMESTAMP timestamp - 4 TIMESTAMP config-timestamp - 2 INT16 x - 2 INT16 y - 2 ROTATION rotation - 2 CARD16 rate - 2 SETofROTATION rotations - 2 SIZEID or Disabled default-size-id - 2 CARD16 start offset in LISTofSCREENSIZE - 2 CARD16 number of SCREENSIZE - 2 CARD16 CARD16 offset in LISTofREFRESH - 2 CARD16 number of CARD16 in refresh rates - - - RRSetMonitorConfig - - 1 CARD8 major opcode - 1 0x09 RandR opcode - 2 7 length - 4 DRAWABLE drawable - 4 TIMESTAMP timestamp - 4 TIMESTAMP config timestamp - 2 SIZEID size index - 2 ROTATION rotation/reflection - 2 CARD16 rate - 2 MONITOR monitor index - 2 INT16 x - 2 INT16 y - -> - 1 1 Reply - 1 RRCONFIGSTATUS status - 2 CARD16 sequence number - 4 0 reply length - 4 TIMESTAMP new timestamp - 4 TIMESTAMP new configuration timestamp - 4 WINDOW root - 2 SUBPIXELORDER subpixel order defined in Render - 2 MONITOR monitor - 4 CARD32 pad6 - 4 CARD32 pad7 - - -A.3 Protocol Events - - RRScreenChangeNotify - - 1 Base + 0 code - 1 ROTATION new rotation and reflection - 2 CARD16 sequence number - 4 TIMESTAMP timestamp - 4 TIMESTAMP configuration timestamp - 4 WINDOW root window - 4 WINDOW request window - 2 SIZEID size ID - 2 SUBPIXELORDER subpixel order defined in Render - 2 CARD16 width in pixels - 2 CARD16 height in pixels - 2 CARD16 width in millimeters - 2 CARD16 height in millimeters - -A.3.1 Protocol Events added with version 1.2 - -Bibliography - -[RANDR] Gettys, Jim and Keith Packard, "The X Resize and Rotate - Extension - RandR", Proceedings of the 2001 USENIX Annual - Technical Conference, Boston, MA - -[RENDER] - Packard, Keith, "The X Rendering Extension", work in progress, - documents found in xc/specs/Render. diff --git a/randr.h b/randr.h index 5be0a3b..5975cdc 100644 --- a/randr.h +++ b/randr.h @@ -31,13 +31,18 @@ typedef unsigned short Rotation; typedef unsigned short SizeID; typedef unsigned short SubpixelOrder; +typedef unsigned short XRandrRotation; +typedef unsigned short XRandrSizeID; +typedef unsigned short XRandrSubpixelOrder; +typedef unsigned short XRandrModeID; +typedef unsigned short XRandrMonitor; #define RANDR_NAME "RANDR" #define RANDR_MAJOR 1 -#define RANDR_MINOR 1 +#define RANDR_MINOR 2 #define RRNumberErrors 0 -#define RRNumberEvents 1 +#define RRNumberEvents 2 #define X_RRQueryVersion 0 /* we skip 1 to make old clients fail pretty immediately */ @@ -50,11 +55,25 @@ typedef unsigned short SubpixelOrder; #define X_RRSelectInput 4 #define X_RRGetScreenInfo 5 -/* used in XRRSelectInput */ +/* V1.2 additions */ +#define X_RRGetScreenSizeRange 6 +#define X_RRSetScreenSize 7 +#define X_RRGetMonitorInfo 8 +#define X_RRAddMonitorMode 9 +#define X_RRDeleteMonitorMode 10 +#define X_RRSetMonitorConfig 11 +/* Event selection bits */ #define RRScreenChangeNotifyMask (1L << 0) +/* V1.2 additions */ +#define RRMonitorChangeNotifyMask (1L << 1) +/* Event codes */ #define RRScreenChangeNotify 0 +/* V1.2 additions */ +#define RRNotify 1 +/* RRNotify Subcodes */ +#define RRNotify_MonitorChange 0 /* used in the rotation field; rotation and reflection in 0.1 proto. */ #define RR_Rotate_0 1 @@ -72,4 +91,22 @@ typedef unsigned short SubpixelOrder; #define RRSetConfigInvalidTime 2 #define RRSetConfigFailed 3 +/* new in 1.2 protocol */ +#define RR_MonitorDisabled 0xffff + +#define RR_HSyncPositive 0x00000001 +#define RR_HSyncNegative 0x00000002 +#define RR_VSyncPositive 0x00000004 +#define RR_VSyncNegative 0x00000008 +#define RR_Interlace 0x00000010 +#define RR_DoubleScan 0x00000020 +#define RR_CSync 0x00000040 +#define RR_CSyncPositive 0x00000080 +#define RR_CSyncNegative 0x00000100 +#define RR_HSkewPresent 0x00000200 +#define RR_BCast 0x00000400 +#define RR_PixelMultiplex 0x00000800 +#define RR_DoubleClock 0x00001000 +#define RR_ClockDivideBy2 0x00002000 + #endif /* _RANDR_H_ */ diff --git a/randrproto.h b/randrproto.h index bfa3976..227a49b 100644 --- a/randrproto.h +++ b/randrproto.h @@ -47,6 +47,7 @@ #define Rotation CARD16 #define SizeID CARD16 #define SubpixelOrder CARD16 +#define ModeID CARD16 /* * data structures diff --git a/randrproto.txt b/randrproto.txt new file mode 100644 index 0000000..e929486 --- /dev/null +++ b/randrproto.txt @@ -0,0 +1,1023 @@ + The X Resize, Rotate and Reflect Extension + Version 1.2 + 2006-4-13 + + Jim Gettys + Jim.Gettys@hp.com + Cambridge Research Laboratory + HP Labs + Hewlett Packard Company + + Keith Packard + keith.packard@intel.com + Open Source Technology Center + Intel Corporation + +1. Introduction + +The X Resize, Rotate and Reflect Extension, called RandR for short, +brings the ability to resize, rotate and reflect the root window of a +screen. It is based on the X Resize and Rotate Extension as specified +in the Proceedings of the 2001 Usenix Technical Conference [RANDR]. + +RandR as implemented and integrated into the X server differs in +one substantial fashion from the design discussed in that paper: that +is, RandR 1.0 does not implement the depth switching described in that +document, and the support described for that in the protocol in that +document and in the implementation has been removed from the +protocol described here, as it has been overtaken by events. + +These events include: + o Modern toolkits (in this case, GTK+ 2.x) have progressed to the point + of implementing migration between screens of arbitrary depths + o The continued advance of Moore's law has made limited amounts of VRAM + less of an issue, reducing the pressure to implement depth switching + on laptops or desktop systems + o The continued decline of legacy toolkits whose design would have + required depth switching to support migration + o The lack of depth switchin implementation experience in the + intervening time, due to events beyond our control + +Additionally, the requirement to support depth switching might +complicate other re-engineering of the device independent part of the +X server that is currently being contemplated. + +Rather than further delaying RandR's widespread deployment for a feature +long wanted by the community (resizing of screens, particularly on laptops), +or the deployment of a protocol design that might be flawed due to lack of +implementation experience, we decided to remove depth switching from the +protocol. It may be implementated at a later time if resources and +interests permit as a revision to the protocol described here, which will +remain a stable base for applications. The protocol described here has been +implemented in the main X.org server, and more fully in the hw/kdrive +implementation in the distribution, which fully implements resizing, +rotation and reflection. + +1.2 Introduction to version 1.2 of the extension + +One of the significant limitations found in version 1.1 of the RandR +protocol was the inability to deal with the Xinerama model where multiple +monitors display portions of a common underlying screen. In this environment, +the size of the 'porthole' shown by each monitor is independent of the +overall size of the screen, and the porthole may be located anywhere within +the screen. + +The effect is to decouple the reported size of the screen from the size +presented by each monitor, and to permit multiple monitors to present +information for a single screen. + +To extend RandR for this model, we separate out the monitor and screen +configuration information and permit them to be configured separately. For +compatibility with the 1.1 version of the protocol, we make the 1.1 requests +simultaneously affect both the screen and the (presumably sole) monitor. +Monitor configuration is now done with full mode information instead of just +size and refresh rate, and these modes have names. These names should use +UTF-8 encoding, but there isn't any enforcement in the specification. +New modes may also be added by the user. + +Additional requests and events are provided for this new functionality. + +2. Acknowlegements + +Our thanks to the contributors to the design found on the xpert mailing +list, in particular: + +Alan Hourihane for work on the early implementation +Andrew C. Aitchison for help with the XFree86 DDX implementation +Andy Ritger for early questions about how mergefb/Xinerama work with RandR +Carl Worth for editing the specification and Usenix paper +David Dawes for XFree86 DDX integration work +Thomas Winischhofer for the hardware-accelerated SiS rotation implementation + +2. Screen change model + +Screens may change dynamically, either under control of this +extension, or due to external events. Examples include: monitors being +swapped, you pressing a button to switch from internal display to an +external monitor on a laptop, or, eventually, the hotplug of a display +card entirely on busses such as Cardbus which permit hot-swap (which +will require other work in addition to this extension). + +Since the screen configuration is dynamic and asynchronous to the +client and may change at any time RandR provides mechanisms to ensure +that your clients view is up to date with the configuration +possibilities of the moment and enforces applications that wish to +control the configuration to prove that their information is up to +date before honoring requests to change the screen configuration (by +requiring a timestamp on the request). + +Interested applications are notified whenever the screen configuration +changes, providing the current size of the screen and subpixel order +(see the Render extension [RENDER]), to enabel proper rendering of +subpixel decimated client text to continue, along with a time stamp of +the configuration change. A client must refresh its knowledge of the +screen configuration before attempting to change the configuration +after a notification, or the request will fail. + +To avoid multiplicative explosion between orientation, reflection +and sizes, the sizes are only those sizes in the normal (0) rotation. + +Rotation and reflection and how they interact can be confusing. In +Randr, the coordinate system is rotated in a counter-clockwise +direction relative to the normal orientation. Reflection is along the +window system coordinate system, not the physical screen X and Y axis, +so that rotation and reflection do not interact. The other way to +consider reflection is to is specified in the "normal" orientation, +before rotation, if you find the other way confusing. + +We expect that most clients and toolkits will be oblivious to changes +to the screen stucture, as they generally use the values in the +connections Display structure directly. By toolkits updating the +values on the fly, we believe pop-up menus and other pop up windows +will position themselves correctly in the face of screen configuration +changes (the issue is ensuring that pop-ups are visible on the +reconfigured screen). + +3. Data Types + +The subpixel order is shared with the Render extension, and is +documented there. The only datatype defined is the screen size, +defined in the normal (0 degree) orientation. + +4. Errors + +There are no new error types defined by this extension. + +5. Protocol Types + +RRCONFIGSTATUS { + Success + InvalidConfigTime + InvalidTime + Failed } +ROTATION { + Rotate_0 + Rotate_90 + Rotate_180 + Rotate_270 + Reflect_X + Reflect_Y } + +RRSELECTMASK { RRScreenChangeNotifyMask + RRMonitorChangeNotifyMask (New in version 1.2) } + +SIZEID { CARD16 } + +MODEID { CARD16 or Disabled } + +MONITOR { CARD16 } + +SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render + SubPixelHorizontalRGB extensions definitions; they are here + SubPixelHorizontalBGR only for convenience. + SubPixelVerticalRGB + SubPixelVerticalBGR + SubPixelNone } + +SCREENSIZE { + widthInPixels, heightInPixels: CARD16 + widthInMillimeters, heightInMillimeters: CARD16 } + + +MODEFLAG { + hsync_positive hsync_negative + vsync_positive vsync_negative + interlace double_scan + csync csync_positive csync_negative + hskew_present + bcast + pixel_multiplex + double_clock + clock_divide_by_2 +} + +MONITORMODE { + name: STRING + widthInPixels, heightInPixels: CARD16 + widthInMillimeters, heightInMillimeters: CARD32 + dotClock: CARD32 + hSyncStart, hSyncEnd, hTotal, hSkew: CARD16 + vSyncStart, vSyncEnd, vTotal: CARD16 + modeFlags: SETofMODEFLAG +} + +REFRESH { + rates: LISTofCARD16 } + +6. Extension Initialization + +The name of this extension is "RANDR". + +RRQueryVersion + client-major-version: CARD32 + client-minor-version: CARD32 + -> + major-version: CARD32 + minor-version: CARD32 + + The client sends the highest supported version to the server + and the server sends the highest version it supports, but no + higher than the requested version. Major versions changes can + introduce incompatibilities in existing functionality, minor + version changes introduce only backward compatible changes. + It is the clients responsibility to ensure that the server + supports a version which is compatible with its expectations. + +7. Extension Requests + +RRSelectInput + window: WINDOW + enable: SETofRRSELECTMASK + + Errors: Window, Value + + If 'enable' is RRScreenChangeNotifyMask, RRScreenChangeNotify events + will be sent when the screen configuration changes, either from + this protocol extension, or due to detected external screen + configuration changes. RRScreenChangeNotify may also be sent when + this request executes if the screen configuration has changed since + the client connected, to avoid race conditions. + + New for version 1.2 - if 'enable' contains RRMonitorChangeMask, + RRMonitorChangeNotify events will be sent when a the configuration + for a monitor associated with the screen changes, either through + this protocol extension or due to detected external monitor changes. + RRMonitorChangeNotify may also be sent when this request executes if + the monitor configuration has changed since the client connected, to + avoid race conditions. + +RRSetScreenConfig + drawable: DRAWABLE + timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + size-id: SIZEID + rotation: ROTATION + rate: CARD16 + + -> + + status: RRCONFIGSTATUS + new-timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + root: WINDOW + subpixelOrder: SUBPIXELORDER + + Errors: Value, Match + + If 'timestamp' is less than the time when the configuration was last + successfully set, the request is ignored and InvalidTime returned in + status. + + If 'config-timestamp' is not equal to when the server's screen + configurations last changed, the request is ignored and + InvalidConfigTime returned in status. This could occur if the + screen changed since you last made a RRGetScreenInfo request, + perhaps by a different piece of display hardware being installed. + Rather than allowing an incorrect call to be executed based on stale + data, the server will ignore the request. + + 'rate' contains the desired refresh rate. If it is zero, the server + selects an appropriate rate. + + This request may fail for other indeterminate reasons, in which case + 'status' will be set to Failed and no configuration change will be + made. + + This request sets the screen to the specified size, rate, rotation + and reflection. + + When this request succeeds, 'status' contains Success and the + requested changes to configuration will have been made. + + 'new-time-stamp' contains the time at which this request was + executed. + + 'config-timestamp' contains the time when the possible screen + configurations were last changed. + + 'root' contains the root window for the screen indicated by the + drawable. + + 'subpixelOrder' contains the resulting subpixel order of the screen + to allow correct subpixel rendering. + + Value errors are generated when 'rotation', 'rate' or 'size-id' + are invalid. + +RRGetScreenInfo + window: WINDOW + + -> + + rotations: SETofROTATION + root: WINDOW + timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + size-id: SIZEID + rotation: ROTATION + rate: CARD16 + sizes: LISTofSCREENSIZE + refresh: LISTofREFRESH + + where: + + Errors: Window + + RRGetScreenInfo returns information about the current and available + configurations for the screen associated with 'window'. + + 'rotations' contains the set of rotations and reflections supported + by the screen. + + 'root' is the root window of the screen. + + 'config-timestamp' indicates when the screen configuration + information last changed: requests to set the screen will fail + unless the timestamp indicates that the information the client + is using is up to date, to ensure clients can be well behaved + in the face of race conditions. + + 'timestamp' indicates when the configuration was last set. + + 'size-id' indicates which size is active. + + 'rate' is the current refresh rate. This is zero when the refresh + rate is unknown or on devices for which refresh is not relevant. + + 'sizes' is the list of possible frame buffer sizes (at the normal + orientation. Each size indicates both the linear physical size of + the screen and the pixel size. + + 'refresh' is the list of refresh rates for each size. Each element + of 'sizes' has a cooresponding element in 'refresh'. An empty list + indicates no known rates, or a device for which refresh is not + relevant. + + The default size of the screen (the size that would become the + current size when the server resets) is the first size in the + list. + +7.1. Extension Requests added in version 1.2 of the extension + +As introduced above, version 1.2 of the extension splits the screen size +from the monitor configuration, permitting the subset of the screen +presented by multiple monitors to be configured. As a separate notion, the +size of the screen itself may be arbitrarily configured within a defined +range. As monitors are added and removed from the system, the set returned +by RRGetMonitorModes will change so that applications can detect dynamic +changes in the monitor environment. + +RRGetScreenSizeRange + drawable: DRAWABLE + + -> + + CARD16 minWidth, minHeight + CARD16 maxWidth, maxHeight + + Errors: Drawable + + Returns the range of possible screen sizes. The screen may be set to + any size within this range. + +RRSetScreenSize + drawable: DRAWABLE + width: CARD16 + height: CARD16 + + Errors: Drawable, Match, Value + + Sets the screen to the specified size. 'width' and 'height' must be + within the range allowed by GetScreenSizeRanges, otherwise a Value + error results. All active monitors must be configured to display a + subset of the specified size, else a Match error results. + +RRGetMonitorModes + drawable: DRAWABLE + + -> + + root: WINDOW + monitors: LISTofMONITORINFO + + where: + + MONITORINFO { + timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + x, y: INT16 + mode: MODEID + rotation: ROTATION + rotations: SETofROTATION + default-mode: MODEID + modes: LISTofMONITORMODE + } + + Errors: Drawable + + RRGetMonitorInfo returns information about the current and available + configurations for all monitors connected to the screen associated + with 'window'. + + 'root' is the root window of the screen. + + 'timestamp' indicates when the configuration was last set. + + 'config-timestamp' indicates when the screen configuration + information last changed: requests to set the screen will fail + unless the timestamp indicates that the information the client + is using is up to date, to ensure clients can be well behaved + in the face of race conditions. + + 'x' and 'y' indicate the position of this monitor within the screen + region. They will be set to 0 when the monitor is disabled. + + 'mode' indicates which mode is active, or 'Disabled' indicating + that the monitor has been disabled and is not displaying the screen + contents. + + 'rotation' indicates the active rotation. It is set to Rotate_0 + when the monitor is disabled. + + 'rotations' contains the set of rotations and reflections supported + by the monitor. + + 'default-mode' is the mode the monitor is set to at server + reset time. + + 'modes' is the list of possible displayed modes. Within each mode, + the sizes are reported for rotation set to Rotate_0. + +RRAddMonitorMode + drawable: DRAWABLE + monitor-index: MONITOR + mode: MONITORMODE + config-timestamp: TIMESTAMP + timestamp: TIMESTAMP + + -> + + Errors: Drawable, Value, Match, Name + + 'drawable' and 'monitor-index' indicate which monitor is to be + configured. If 'monitor-index' is out of range, a Value error is + returned. + + 'mode' provides a new mode for the monitor. If the name of 'mode' + names an existing mode, a Name error is returned. If 'mode' cannot be + supported by the specified monitor, a Match error is returned. If + some parameter of the mode is not valid in some other way, a Value + error is returned. + + This request generates MonitorChangeNotify events. + +RRDeleteMonitorMode + drawable: DRAWABLE + monitor-index: MONITOR + name: STRING + + -> + + Errors: Drawable, Value, Name + + 'drawable' and 'monitor-index' indicate which monitor is to be + configured. If 'monitor-index' is out of range, a Value error is + returned. + + 'name' specifies which mode to delete. If no mode of the specified + name exists, a Name error is returned. The named mode must have + been added with RRAddMonitorMode, else an Access error is returned. + The named mode must not be active, else a Match error is returned. + +RRSetMonitorMode + drawable: DRAWABLE + monitor-index: MONITOR + timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + x, y: INT16 + mode: MODEID + rotation: ROTATION + + -> + + status: RRCONFIGSTATUS + new-timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + root: WINDOW + monitor: MONITOR + subpixelOrder: SUBPIXELORDER + + Errors: Value, Match + + If 'timestamp' is less than the time when the configuration was last + successfully set, the request is ignored and InvalidTime returned in + status. + + If 'config-timestamp' is not equal to when the monitor's + configuration last changed, the request is ignored and + InvalidConfigTime returned in status. This could occur if the + monitor changed since you last made a RRGetScreenInfo request, + perhaps by a different monitor being connected to the machine. + Rather than allowing an incorrect call to be executed based on stale + data, the server will ignore the request. + + 'x' and 'y' contain the desired location within the screen for this + monitor's content. 'x' and 'y' must be within the screen size, else + a Value error results. + + 'mode' contains the index of desired mode or Disabled indicating the + monitor should be disabled. If 'mode' is not one of these values, a + Value error results. + + 'rotation' contains the desired rotation along with which + reflections should be enabled. The rotation and reflection values + must be among those allowed for this monitor, else a Value error + results. + + This request may fail for other indeterminate reasons, in which case + 'status' will be set to Failed and no configuration change will be + made. + + This request sets the monitor to the specified position, mode, + rotation and reflection. The entire area of the monitor must fit + within the screen size, else a Match error results. As an example, + rotating the screen so that a single monitor fills the entire screen + before and after may necessitate disabling the monitor, resizing the + screen, then re-enabling the monitor at the new configuration to + avoid an invalid intermediate configuration. + + When this request succeeds, 'status' contains Success and the + requested changes to configuration will have been made. + + 'new-time-stamp' contains the time at which this request was + executed. + + 'config-timestamp' contains the time when the possible screen + configurations were last changed. + + 'root' contains the root window for the screen indicated by the + drawable. + + 'subpixelOrder' contains the resulting subpixel order of the monitor + to allow correct subpixel rendering. + +8. Extension Events + +Clients MAY select for ConfigureNotify on the root window to be +informed of screen changes. This may be advantageous if all your +clients need to know is the size of the root window, as it avoids +round trips to set up the extension. + +RRScreenChangeNotify is sent if RRSelectInput has requested it +whenever properties of the screen change, which may be due to external +factors, such as recabling a monitor, etc. + +RRScreenChangeNotify + + rotation: ROTATION; new rotation + sequenceNumber: CARD16 low 16 bits of request's seq. number + timestamp: TIMESTAMP time screen was changed + configTimestamp: TIMESTAMP time config data was changed + root: WINDOW root window of screen + window: WINDOW window requesting notification + size-id: SIZEID index of new size + subpixelOrder: SUBPIXELORDER order of subpixels + widthInPixels: CARD16 + heightInPixels: CARD16 + widthInMillimeters: CARD16 + heightInMillimeters: CARD16 + + This event is generated whenever the screen configuration is changed + and sent to requesting clients. 'timestamp' indicates when the + screen configuration was changed. 'configTimestamp' says when the + last time the configuration was changed. 'root' is the root of the + screen the change occurred on, 'window' is window selecting for this + event. 'size-id' contains the index of the current size. + + This event is sent whenever the screen's configuration changes + or if a new screen configuration becomes available that was + not available in the past. In this case (config-timestamp in + the event not being equal to the config-timestamp returned in + the last call to RRGetScreenInfo), the client MUST call + RRGetScreenInfo to update its view of possible screen + configurations to have a correct view of possible screen + organizations. + + Clients which select screen change notification events may be + sent an event immediately if the screen configuration was + changed between when they connected to the X server and + selected for notification. This is to prevent a common race + that might occur on log-in, where many applications start up + just at the time when a display manager or log in script might + be changing the screen size or configuration. + +8.1 Events added in version 1.2 of the RandR extension + +RRMonitorChangeNotify + + rotation: ROTATION; new rotation + sequenceNumber: CARD16 low 16 bits of request's seq. number + timestamp: TIMESTAMP time monitor was changed + configTimestamp: TIMESTAMP time config data was changed + root: WINDOW root window of screen + window: WINDOW window requesting notification + monitor-index: MONITOR monitor which changed + mode: MODEID new mode + subpixelOrder: SUBPIXELORDER order of subpixels + x: INT16 x position of monitor within screen + y: INT16 y position of monitor within screen + + This event is generated whenever the monitor configuration is changed + and sent to requesting clients. 'timestamp' indicates when the + monitor configuration was changed. 'configTimestamp' says when the + last time the configuration was changed. 'root' is the root of the + screen the change occurred on, 'window' is window selecting for this + event. 'size-id' contains the index of the current size. + + This event is sent whenever the monitor's configuration changes + or if a new monitor configuration becomes available that was + not available in the past. In this case (config-timestamp in + the event not being equal to the config-timestamp returned in + the last call to RRGetMonitorInfo), the client MUST call + RRGetMonitorInfo to update its view of possible monitor + configurations to have a correct view of possible monitor + organizations. + + Clients which select monitor change notification events may be + sent an event immediately if the monitor configuration was + changed between when they connected to the X server and + selected for notification. This is to prevent a common race + that might occur on log-in, where many applications start up + just at the time when a display manager or log in script might + be changing the monitor size or configuration. + +9. Extension Versioning + +The RandR extension was developed in parallel with the implementation +to ensure the feasibility of various portions of the design. As +portions of the extension are implemented, the version number of the +extension has changed to reflect the portions of the standard provied. +This document describes the version 1.0 of the specification, the +partial implementations have version numbers less than that. Here's a +list of what each version before 1.0 implemented: + + 0.0: This prototype implemented resize and rotation in the + TinyX server Used approximately the protocol described in + the Usenix paper. Appeared in the TinyX server in + XFree86 4.2, but not in the XFree86 main server. + + 0.1: Added subpixel order, added an event for subpixel order. + This version was never checked in to XFree86 CVS. + + 1.0: Implements resize, rotation, and reflection. Implemented + both in the XFree86 main server (size change only at this + date), and fully (size change, rotation, and reflection) + in XFree86's TinyX server. + + 1.1: Added refresh rates + + 1.2: Separate out screens from monitors, switch to full VESA modes + +Compatibility between 0.0 and 1.0 was *NOT* preserved, and 0.0 clients +will fail against 1.0 servers. The wire encoding op-codes were +changed for GetScreenInfo to ensure this failure in a relatively +graceful way. Version 1.1 servers and clients are cross compatible with +1.0. Version 1.1 is considered to be stable and we intend upward +compatibility from this point. + +10. Relationship with other extensions + +Two other extensions have a direct relationship with this extension. This +section attempts to explain how these three are supposed to work together. + +10.1 XFree86-VidModeExtension + +XFree86-VidModeExtension changes the configuration of a single monitor +attached to the screen without changing the configuration of the screen +itself. It provides the ability to specify new mode lines for the server to +use along with selecting among existing mode lines. As it uses screen +numbers instead of window identifiers, it can be used to affect multiple +monitors in a single-screen Xinerama configuration. However, the association +between screen numbers and root windows in a multi-Screen environment is not +defined by the extension. Version 2.0 of this extension added the ability to +adjust the DAC values in a TrueColor server to modify the brightness curves +of the display. + +Most of the utility of this extension is subsumed by RandR version 1.2, +except for the gamma adjustments. If this features continue to be useful, +either some relationship between the screen indices used in the +XFree86-VidModeExtension and the screen/monitor pairs used int RandR or an +incorporation of this functionality into RandR might be needed. + +10.2 Xinerama + +Xinerama provides a mechanism for describing the relationship between the +overall screen display and monitors placed within that area. As such, it +provides the query functionality of RandR 1.2 without any of the +configuration functionality. Applications using Xinerama to discover +monitor geometry can continue to do so, with the caveat that they will not be +informed of changes when they occur. However, Xinerama configuration data +will be updated, so applications selecting for RandR notification and +re-querying the configuration with the Xinerama extension will get updated +information. It is probably better to view RandR as a superset of Xinerama +at this point and use it in preference to Xinerama where both are present. + +Appendix A. Protocol Encoding + +Syntactic Conventions + +This document uses the same syntactic conventions as the core X +protocol encoding document. + + +A.1 Common Types + + ROTATION + 0x0001 Rotate_0 + 0x0002 Rotate_90 + 0x0004 Rotate_180 + 0x0008 Rotate_270 + 0x0010 Reflect_X + 0x0020 Reflect_Y + + + RRSELECTMASK + 0x0001 ScreenChangeNotifyMask + 0x0002 MonitorChangeNotifyMask Added in version 1.2 + + RRCONFIGSTATUS + 0x0 Success + 0x1 InvalidConfigTime + 0x2 InvalidTime + 0x3 Failed + + SIZEID + 0xffff Disabled + + MONITORMODE (36) Added in version 1.2 + 2 CARD16 width in pixels + 2 CARD16 height in pixels + 4 CARD32 width in millimeters + 4 CARD32 height in millimeters + 4 CARD32 dot clock + 2 CARD16 h sync start + 2 CARD16 h sync end + 2 CARD16 h total + 2 CARD16 h skew + 2 CARD16 v sync start + 2 CARD16 v sync end + 2 CARD16 v total + 2 CARD16 name length (n) + 4 SETofMODEFLAG mode flags + + The location of the name in the encoding is specified separately + +A.2 Protocol Requests + + +Opcodes 0x1 and 0x3 were used in the 0.0 protocols, and will return +errors if used in version 1.0. + + RRQueryVersion + + 1 CARD8 major opcode + 1 0x01 RandR opcode + 2 3 length + 4 CARD32 major version + 4 CARD32 minor version + -> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 reply length + 1 CARD32 major version + 1 CARD32 minor version + + + RRSetScreenConfig + + 1 CARD8 major opcode + 1 0x02 RandR opcode + 2 6 length + 4 DRAWABLE drawable on screen to be configured + 4 TIMESTAMP timestamp + 4 TIMESTAMP config timestamp + 2 SIZEID size index + 2 ROTATION rotation/reflection + 2 CARD16 refresh rate (1.1 only) + 2 CARD16 pad + -> + 1 1 Reply + 1 RRCONFIGSTATUS status + 2 CARD16 sequence number + 4 0 reply length + 4 TIMESTAMP new timestamp + 4 TIMESTAMP new configuration timestamp + 4 WINDOW root + 2 SUBPIXELORDER subpixel order defined in Render + 2 CARD16 pad4 + 4 CARD32 pad5 + 4 CARD32 pad6 + + + RRSelectInput + + 1 CARD8 major opcode + 1 0x04 RandR opcode + 2 3 length + 4 WINDOW window + 2 SETofRRSELECTMASK enable + 2 CARD16 pad + + + RRGetScreenInfo + + 1 CARD8 major opcode + 1 0x05 RandR opcode + 2 2 length + 4 WINDOW window + -> + 1 1 Reply + 1 CARD8 set of Rotations + 2 CARD16 sequence number + 4 0 reply length + 4 WINDOW root window + 4 TIMESTAMP timestamp + 4 TIMESTAMP config timestamp + 2 CARD16 number of SCREENSIZE following + 2 SIZEID current size index + 2 ROTATION current rotation and reflection + 2 CARD16 current rate (added in version 1.1) + 2 CARD16 length of rate info (number of CARD16s) + 2 CARD16 pad + + SCREENSIZE + 2 CARD16 width in pixels + 2 CARD16 height in pixels + 2 CARD16 width in millimeters + 2 CARD16 height in millimeters + + REFRESH + 2 CARD16 number of rates (n) + 2n CARD16 rates + +A.2.1 Protocol Requests added with version 1.2 + + RRGetScreenSizeRange + + 1 CARD8 major opcode + 1 0x06 RandR opcode + 2 2 length + 4 DRAWABLE drawable + -> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 reply length + 2 CARD16 minWidth + 2 CARD16 minHeight + 2 CARD16 maxWidth + 2 CARD16 maxHeight + 4 unused + 4 unused + 4 unused + 4 unused + + + RRSetScreenSize + + 1 CARD8 major opcode + 1 0x07 RandR opcode + 2 3 length + 4 DRAWABLE drawable + 2 CARD16 width + 2 CARD16 height + + + RRGetMonitorInfo + + 1 CARD8 major opcode + 1 0x08 RandR opcode + 2 2 length + 4 DRAWABLE drawable + -> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 i*6 + m*9 + (b+p)/4 reply length + 4 WINDOW root + 2 CARD16 i = number of MONITORINFO following + 2 CARD16 m = number of SIZE following + 2 CARD16 b = size of name array following + 14 unused + i*24 LISTofMONITORINFO one per monitor + m*36 LISTofMONITORMODE for all monitors + b LISTofCARD* list of mode names + p pad pad(b) + + MONITORINFO + 4 TIMESTAMP timestamp + 4 TIMESTAMP config-timestamp + 2 INT16 x + 2 INT16 y + 2 ROTATION rotation + 2 MODEID mode + 2 MODEID default mode + 2 SETofROTATION rotations + 2 CARD16 start offset in LISTofMONITORMODE + 2 CARD16 number of MONITORMODE + + RRAddMonitorMode + 1 CARD8 major opcode + 1 0x09 RandR opcode + 2 9+(b+p)/4 length + 4 DRAWABLE drawable + 2 MONITOR monitor index + 2 unused + 24 MONITORMODE mode + b STRING mode name + p pad(b) + + RRDeleteMonitorMode + 1 CARD8 major opcode + 1 0x0a RandR opcode + 2 3+(b+p)/4 length + 4 DRAWABLE drawable + 2 MONITOR monitor index + 2 CARD16 mode name length + b STRING mode name + p pad(b) + + RRSetMonitorConfig + + 1 CARD8 major opcode + 1 0x0b RandR opcode + 2 7 length + 4 DRAWABLE drawable + 4 TIMESTAMP timestamp + 4 TIMESTAMP config timestamp + 2 SIZEID size index + 2 ROTATION rotation/reflection + 2 CARD16 rate + 2 MONITOR monitor index + 2 INT16 x + 2 INT16 y + -> + 1 1 Reply + 1 RRCONFIGSTATUS status + 2 CARD16 sequence number + 4 0 reply length + 4 TIMESTAMP new timestamp + 4 TIMESTAMP new configuration timestamp + 4 WINDOW root + 2 SUBPIXELORDER subpixel order defined in Render + 2 MONITOR monitor + 4 CARD32 pad6 + 4 CARD32 pad7 + + +A.3 Protocol Events + + RRScreenChangeNotify + + 1 Base + 0 code + 1 ROTATION new rotation and reflection + 2 CARD16 sequence number + 4 TIMESTAMP timestamp + 4 TIMESTAMP configuration timestamp + 4 WINDOW root window + 4 WINDOW request window + 2 SIZEID size ID + 2 SUBPIXELORDER subpixel order defined in Render + 2 CARD16 width in pixels + 2 CARD16 height in pixels + 2 CARD16 width in millimeters + 2 CARD16 height in millimeters + +A.3.1 Protocol Events added with version 1.2 + + RRMonitorChangeNotify + + 1 Base + 1 code + 1 0 sub-code + 2 CARD16 sequence number + 4 TIMESTAMP timestamp + 4 TIMESTAMP configuration timestamp + 4 WINDOW root window + 4 WINDOW request window + 2 MONITOR monitor index + 2 MODEID mode ID + 2 CARD16 x + 2 CARD16 y + 1 ROTATION new rotation and reflection + 3 unused + +Bibliography + +[RANDR] Gettys, Jim and Keith Packard, "The X Resize and Rotate + Extension - RandR", Proceedings of the 2001 USENIX Annual + Technical Conference, Boston, MA + +[RENDER] + Packard, Keith, "The X Rendering Extension", work in progress, + documents found in xc/specs/Render. -- cgit v1.2.1 From bbaabdd10585aed3bc44f2179ec4a68975a599cc Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Mon, 26 Jun 2006 14:33:18 +0200 Subject: Finish randerproto.h change for 1.2. Use Window instead of Drawable for 1.2. --- randrproto.h | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- randrproto.txt | 90 +++++++++++++++++-------------- 2 files changed, 213 insertions(+), 43 deletions(-) diff --git a/randrproto.h b/randrproto.h index 227a49b..e3083f9 100644 --- a/randrproto.h +++ b/randrproto.h @@ -171,7 +171,153 @@ typedef struct { } xRRSelectInputReq; #define sz_xRRSelectInputReq 12 -#define sz_xRRSelectInputReq 12 +/* + * Additions for version 1.2 + */ + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + Window window B32; +} xRRGetScreenSizeRangeReq; +#define sz_xRRGetScreenSizeRangeReq 8 + +typedef struct { + BYTE type; /* X_Reply */ + CARD8 status; + 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; +} xRRGetMonitorModesReq; + +typedef struct { + BYTE type; /* X_Reply */ + CARD8 status; + CARD16 sequenceNumber B16; + CARD32 length B32; + Window root B32; + CARD16 i B16; + CARD16 m B16; + CARD16 b B16; + CARD16 pad0 B16; + CARD32 pad1 B32; + CARD32 pad2 B32; + CARD32 pad3 B32; +} xRRGetMonitorModesReply; +#define sz_xRRGetMonitorModesReply 32 + +typedef struct { + Time timestamp B32; + Time configTimestamp B32; + INT16 x B16; + INT16 y B16; + Rotation rotation B16; + ModeID mode B16; + ModeID defaultMode B16; + Rotation rotations B16; + CARD16 firstMode B16; + CARD16 numModes B16; +} xRRMonitorInfo; +#define sz_xRRMonitorInfo 24 + +typedef struct { + CARD16 width B16; + CARD16 height B16; + CARD32 widthInMillimeters B32; + CARD32 heightInMillimeters B32; + 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; + CARD32 modeFlags B32; +} xRRMonitorMode; +#define sz_xRRMonitorMode 36 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + Window window B32; + Monitor monitorIndex B16; + CARD16 pad B16; + xRRMonitorMode mode; +} xRRAddMonitorModeReq; +#define sz_xRRAddMonitorModeReq 48 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + Window window B32; + Monitor monitorIndex B16; + CARD16 nameLength B16; +} xRRDeleteMonitorModeReq; +#define sz_xRRDeleteMonitorModeReq 12 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + Window window B32; + Time timestamp B32; + Time configTimestamp B32; + Monitor monitorIndex B16; + INT16 x B16; + INT16 y B16; + ModeID mode B16; + Rotation rotation B16; + CARD16 pad B16; +} xRRSetMonitorConfigReq +#define sz_xRRSetMonitorConfigReq 28 + +typedef struct { + BYTE type; /* X_Reply */ + CARD8 status; + CARD16 sequenceNumber B16; + CARD32 length B32; + Time timestamp B32; + Time configTimestamp B32; + Window root B32; + SubpixelOrder subpixelOrder B16; + Monitor monitor B16; + CARD32 pad1 B32; + CARD32 pad2 B32; +} xRRSetMonitorConfigReply; + +#define sz_xRRSetMonitorConfigReply /* * event @@ -193,8 +339,24 @@ typedef struct { } xRRScreenChangeNotifyEvent; #define sz_xRRScreenChangeNotifyEvent 32 +typedef struct { + CARD8 type; /* always evBase + RRNotify */ + CARD8 subCode; /* RRNotify_MonitorChange */ + CARD16 sequenceNumber B16; + Time timestamp B32; /* time screen was changed */ + Time configTimestamp B32; /* time config data was changed */ + Window root B32; /* root window */ + Window window B32; /* window requesting notification */ + ModeID modeID B16; /* mode ID */ + INT16 x B16; /* x */ + INT16 y B16; /* y */ + Rotation rotation B16; /* rotation/reflection */ + CARD16 pad B16; +} xRRMonitorChangeNotifyEvent; +#define sz_xRRMonitorChangeNotifyEvent 32 + +#undef Window #undef Window -#undef Drawable #undef Font #undef Pixmap #undef Cursor diff --git a/randrproto.txt b/randrproto.txt index e929486..d85796c 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -247,7 +247,7 @@ RRSelectInput avoid race conditions. RRSetScreenConfig - drawable: DRAWABLE + window: WINDOW timestamp: TIMESTAMP config-timestamp: TIMESTAMP size-id: SIZEID @@ -296,7 +296,7 @@ RRSetScreenConfig configurations were last changed. 'root' contains the root window for the screen indicated by the - drawable. + window. 'subpixelOrder' contains the resulting subpixel order of the screen to allow correct subpixel rendering. @@ -368,32 +368,39 @@ by RRGetMonitorModes will change so that applications can detect dynamic changes in the monitor environment. RRGetScreenSizeRange - drawable: DRAWABLE + window: WINDOW -> CARD16 minWidth, minHeight CARD16 maxWidth, maxHeight - Errors: Drawable + Errors: Window Returns the range of possible screen sizes. The screen may be set to any size within this range. RRSetScreenSize - drawable: DRAWABLE + window: WINDOW width: CARD16 height: CARD16 + width-in-millimeters: CARD32 + height-in-millimeters: CARD32 - Errors: Drawable, Match, Value + 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. + RRGetMonitorModes - drawable: DRAWABLE + window: WINDOW -> @@ -413,9 +420,9 @@ RRGetMonitorModes modes: LISTofMONITORMODE } - Errors: Drawable + Errors: Window - RRGetMonitorInfo returns information about the current and available + RRGetMonitorModes returns information about the current and available configurations for all monitors connected to the screen associated with 'window'. @@ -449,7 +456,7 @@ RRGetMonitorModes the sizes are reported for rotation set to Rotate_0. RRAddMonitorMode - drawable: DRAWABLE + window: WINDOW monitor-index: MONITOR mode: MONITORMODE config-timestamp: TIMESTAMP @@ -457,9 +464,9 @@ RRAddMonitorMode -> - Errors: Drawable, Value, Match, Name + Errors: Window, Value, Match, Name - 'drawable' and 'monitor-index' indicate which monitor is to be + 'window' and 'monitor-index' indicate which monitor is to be configured. If 'monitor-index' is out of range, a Value error is returned. @@ -472,15 +479,15 @@ RRAddMonitorMode This request generates MonitorChangeNotify events. RRDeleteMonitorMode - drawable: DRAWABLE + window: WINDOW monitor-index: MONITOR name: STRING -> - Errors: Drawable, Value, Name + Errors: Window, Value, Name - 'drawable' and 'monitor-index' indicate which monitor is to be + 'window' and 'monitor-index' indicate which monitor is to be configured. If 'monitor-index' is out of range, a Value error is returned. @@ -490,7 +497,7 @@ RRDeleteMonitorMode The named mode must not be active, else a Match error is returned. RRSetMonitorMode - drawable: DRAWABLE + window: WINDOW monitor-index: MONITOR timestamp: TIMESTAMP config-timestamp: TIMESTAMP @@ -556,7 +563,7 @@ RRSetMonitorMode configurations were last changed. 'root' contains the root window for the screen indicated by the - drawable. + window. 'subpixelOrder' contains the resulting subpixel order of the monitor to allow correct subpixel rendering. @@ -638,8 +645,8 @@ RRMonitorChangeNotify or if a new monitor configuration becomes available that was not available in the past. In this case (config-timestamp in the event not being equal to the config-timestamp returned in - the last call to RRGetMonitorInfo), the client MUST call - RRGetMonitorInfo to update its view of possible monitor + the last call to RRGetMonitorModes), the client MUST call + RRGetMonitorModes to update its view of possible monitor configurations to have a correct view of possible monitor organizations. @@ -799,10 +806,10 @@ errors if used in version 1.0. 1 CARD8 major opcode 1 0x02 RandR opcode 2 6 length - 4 DRAWABLE drawable on screen to be configured + 4 WINDOW window on screen to be configured 4 TIMESTAMP timestamp 4 TIMESTAMP config timestamp - 2 SIZEID size index + 2 SIZEID size index 2 ROTATION rotation/reflection 2 CARD16 refresh rate (1.1 only) 2 CARD16 pad @@ -868,7 +875,7 @@ A.2.1 Protocol Requests added with version 1.2 1 CARD8 major opcode 1 0x06 RandR opcode 2 2 length - 4 DRAWABLE drawable + 4 WINDOW window -> 1 1 Reply 1 unused @@ -888,18 +895,20 @@ A.2.1 Protocol Requests added with version 1.2 1 CARD8 major opcode 1 0x07 RandR opcode - 2 3 length - 4 DRAWABLE drawable + 2 5 length + 4 WINDOW window 2 CARD16 width 2 CARD16 height + 4 CARD32 width in millimeters + 4 CARD32 height in millimeters - RRGetMonitorInfo + RRGetMonitorModes 1 CARD8 major opcode 1 0x08 RandR opcode 2 2 length - 4 DRAWABLE drawable + 4 WINDOW window -> 1 1 Reply 1 unused @@ -930,11 +939,11 @@ A.2.1 Protocol Requests added with version 1.2 RRAddMonitorMode 1 CARD8 major opcode 1 0x09 RandR opcode - 2 9+(b+p)/4 length - 4 DRAWABLE drawable + 2 12+(b+p)/4 length + 4 WINDOW window 2 MONITOR monitor index 2 unused - 24 MONITORMODE mode + 36 MONITORMODE mode b STRING mode name p pad(b) @@ -942,26 +951,26 @@ A.2.1 Protocol Requests added with version 1.2 1 CARD8 major opcode 1 0x0a RandR opcode 2 3+(b+p)/4 length - 4 DRAWABLE drawable + 4 WINDOW window 2 MONITOR monitor index 2 CARD16 mode name length b STRING mode name p pad(b) - RRSetMonitorConfig + RRSetMonitorMode 1 CARD8 major opcode 1 0x0b RandR opcode 2 7 length - 4 DRAWABLE drawable + 4 WINDOW window 4 TIMESTAMP timestamp 4 TIMESTAMP config timestamp - 2 SIZEID size index - 2 ROTATION rotation/reflection - 2 CARD16 rate 2 MONITOR monitor index 2 INT16 x 2 INT16 y + 2 MODEID mode index + 2 ROTATION rotation/reflection + 2 unused -> 1 1 Reply 1 RRCONFIGSTATUS status @@ -972,8 +981,7 @@ A.2.1 Protocol Requests added with version 1.2 4 WINDOW root 2 SUBPIXELORDER subpixel order defined in Render 2 MONITOR monitor - 4 CARD32 pad6 - 4 CARD32 pad7 + 8 unused A.3 Protocol Events @@ -1007,10 +1015,10 @@ A.3.1 Protocol Events added with version 1.2 4 WINDOW request window 2 MONITOR monitor index 2 MODEID mode ID - 2 CARD16 x - 2 CARD16 y - 1 ROTATION new rotation and reflection - 3 unused + 2 INT16 x + 2 INT16 y + 2 ROTATION new rotation and reflection + 2 unused Bibliography -- cgit v1.2.1 From c414ce4494f0d062bc25fa671cf50a556c9e1d8c Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Tue, 27 Jun 2006 02:27:10 +0200 Subject: Just use CARD16 for indices --- randrproto.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/randrproto.h b/randrproto.h index e3083f9..a9d5a01 100644 --- a/randrproto.h +++ b/randrproto.h @@ -271,7 +271,7 @@ typedef struct { CARD8 randrReqType; CARD16 length B16; Window window B32; - Monitor monitorIndex B16; + CARD16 monitorIndex B16; CARD16 pad B16; xRRMonitorMode mode; } xRRAddMonitorModeReq; @@ -282,7 +282,7 @@ typedef struct { CARD8 randrReqType; CARD16 length B16; Window window B32; - Monitor monitorIndex B16; + CARD16 monitorIndex B16; CARD16 nameLength B16; } xRRDeleteMonitorModeReq; #define sz_xRRDeleteMonitorModeReq 12 @@ -294,13 +294,13 @@ typedef struct { Window window B32; Time timestamp B32; Time configTimestamp B32; - Monitor monitorIndex B16; + CARD16 monitorIndex B16; INT16 x B16; INT16 y B16; ModeID mode B16; Rotation rotation B16; CARD16 pad B16; -} xRRSetMonitorConfigReq +} xRRSetMonitorConfigReq; #define sz_xRRSetMonitorConfigReq 28 typedef struct { @@ -312,7 +312,7 @@ typedef struct { Time configTimestamp B32; Window root B32; SubpixelOrder subpixelOrder B16; - Monitor monitor B16; + CARD16 monitor B16; CARD32 pad1 B32; CARD32 pad2 B32; } xRRSetMonitorConfigReply; -- cgit v1.2.1 From 5220e7d7dfa64d95918b6f5ad52089fe87540b61 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Tue, 27 Jun 2006 22:38:32 +0200 Subject: Swizzle protocol contents to fix errors discovered while implementing X server piece --- randrproto.h | 5 +++-- randrproto.txt | 13 ++++++++++--- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/randrproto.h b/randrproto.h index a9d5a01..015df9a 100644 --- a/randrproto.h +++ b/randrproto.h @@ -347,11 +347,12 @@ typedef struct { Time configTimestamp B32; /* time config data was changed */ Window root B32; /* root window */ Window window B32; /* window requesting notification */ + CARD16 monitor B16; /* monitor index */ ModeID modeID B16; /* mode ID */ + Rotation rotation B16; /* rotation/reflection */ + SubpixelOrder subpixelOrder B16; /* new subpixel order */ INT16 x B16; /* x */ INT16 y B16; /* y */ - Rotation rotation B16; /* rotation/reflection */ - CARD16 pad B16; } xRRMonitorChangeNotifyEvent; #define sz_xRRMonitorChangeNotifyEvent 32 diff --git a/randrproto.txt b/randrproto.txt index d85796c..5508e62 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -622,7 +622,6 @@ RRScreenChangeNotify RRMonitorChangeNotify - rotation: ROTATION; new rotation sequenceNumber: CARD16 low 16 bits of request's seq. number timestamp: TIMESTAMP time monitor was changed configTimestamp: TIMESTAMP time config data was changed @@ -630,6 +629,7 @@ RRMonitorChangeNotify window: WINDOW window requesting notification monitor-index: MONITOR monitor which changed mode: MODEID new mode + rotation: ROTATION; new rotation subpixelOrder: SUBPIXELORDER order of subpixels x: INT16 x position of monitor within screen y: INT16 y position of monitor within screen @@ -777,6 +777,13 @@ A.1 Common Types 2 CARD16 name length (n) 4 SETofMODEFLAG mode flags + A monitor mode specifies the complete CRTC timings for + a specfic 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 location of the name in the encoding is specified separately A.2 Protocol Requests @@ -1015,10 +1022,10 @@ A.3.1 Protocol Events added with version 1.2 4 WINDOW request window 2 MONITOR monitor index 2 MODEID mode ID + 2 ROTATION new rotation and reflection + 2 SUBPIXELORDER new subpixel order 2 INT16 x 2 INT16 y - 2 ROTATION new rotation and reflection - 2 unused Bibliography -- cgit v1.2.1 From 62decb70de5bbe623859764e7cb492209478e304 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Mon, 11 Sep 2006 21:29:39 -0700 Subject: Start rework for screen/CRTC/monitor scheme. --- randrproto.txt | 316 +++++++++++++++++++++++++++++++++------------------------ 1 file changed, 181 insertions(+), 135 deletions(-) diff --git a/randrproto.txt b/randrproto.txt index 5508e62..6c4e2d6 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -1,23 +1,23 @@ - The X Resize, Rotate and Reflect Extension - Version 1.2 - 2006-4-13 + 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 + 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 + 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 +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 @@ -28,14 +28,14 @@ document and in the implementation has been removed from the protocol described here, as it has been overtaken by events. These events include: - o Modern toolkits (in this case, GTK+ 2.x) have progressed to the point + ► 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 + ► 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 + ► 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 + ► 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 @@ -46,9 +46,9 @@ 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 +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 +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. @@ -58,25 +58,58 @@ rotation and reflection. One of the significant limitations found in version 1.1 of the RandR protocol was the inability to deal with the Xinerama model where multiple monitors display portions of a common underlying screen. In this environment, -the size of the 'porthole' shown by each monitor is independent of the -overall size of the screen, and the porthole may be located anywhere within -the screen. +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 monitor, and to permit multiple monitors to present +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 monitor and 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) monitor. -Monitor configuration is now done with full mode information instead of just -size and refresh rate, and these modes have names. These names should use -UTF-8 encoding, but there isn't any enforcement in the specification. -New modes may also be added by the user. +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┃ ║monitor║ ╚═══════════════════╝ + └──────┘ ┗━━━━┛ ╚═══════╝ + +In this picture, the screen is covered (incompletely) by two CRTCs. CRTC1 +is connected to two monitors, A and B. CRTC2 is connected to monitor C. +Monitors A and B will present exactly the same region of the screen using +the same mode line. Monitor C will present a different (larger) region of +the screen using a different mode line. + +RandR provides information about each available CRTC and monitor; the +connection between CRTC and monitor 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 togther 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. + 2. Acknowlegements Our thanks to the contributors to the design found on the xpert mailing @@ -88,6 +121,8 @@ 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 Tippet and Kevin Martin for splitting outputs and CRTCs to more +fully expose what video hardware can do 2. Screen change model @@ -110,24 +145,24 @@ 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 +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 +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 +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 +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 +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 @@ -136,7 +171,7 @@ 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, +documented there. The only datatype defined is the screen size, defined in the normal (0 degree) orientation. 4. Errors @@ -159,13 +194,16 @@ ROTATION { Reflect_Y } RRSELECTMASK { RRScreenChangeNotifyMask - RRMonitorChangeNotifyMask (New in version 1.2) } + RRCrtcChangeNotifyMask (New in version 1.2) + RROutputChangeNotifyMask (New in version 1.2) } SIZEID { CARD16 } MODEID { CARD16 or Disabled } -MONITOR { CARD16 } +CRTC { CARD16 } + +OUTPUT { CARD16 } SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render SubPixelHorizontalRGB extensions definitions; they are here @@ -178,7 +216,6 @@ SCREENSIZE { widthInPixels, heightInPixels: CARD16 widthInMillimeters, heightInMillimeters: CARD16 } - MODEFLAG { hsync_positive hsync_negative vsync_positive vsync_negative @@ -191,7 +228,7 @@ MODEFLAG { clock_divide_by_2 } -MONITORMODE { +CRTCMODE { name: STRING widthInPixels, heightInPixels: CARD16 widthInMillimeters, heightInMillimeters: CARD32 @@ -199,6 +236,7 @@ MONITORMODE { hSyncStart, hSyncEnd, hTotal, hSkew: CARD16 vSyncStart, vSyncEnd, vTotal: CARD16 modeFlags: SETofMODEFLAG + possible-outputs: LISTofLISTofOUTPUT } REFRESH { @@ -217,7 +255,7 @@ RRQueryVersion 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 + 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 @@ -238,14 +276,22 @@ RRSelectInput this request executes if the screen configuration has changed since the client connected, to avoid race conditions. - New for version 1.2 - if 'enable' contains RRMonitorChangeMask, - RRMonitorChangeNotify events will be sent when a the configuration - for a monitor associated with the screen changes, either through - this protocol extension or due to detected external monitor changes. - RRMonitorChangeNotify may also be sent when this request executes if - the monitor configuration has changed since the client connected, to - avoid race conditions. - + 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. + RRSetScreenConfig window: WINDOW timestamp: TIMESTAMP @@ -270,7 +316,7 @@ RRSetScreenConfig 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 + 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 @@ -341,7 +387,7 @@ RRGetScreenInfo 'size-id' indicates which size is active. - 'rate' is the current refresh rate. This is zero when the refresh + '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 @@ -349,7 +395,7 @@ RRGetScreenInfo 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 + of 'sizes' has a cooresponding element in 'refresh'. An empty list indicates no known rates, or a device for which refresh is not relevant. @@ -399,35 +445,27 @@ RRSetScreenSize extension and the core protocol. They must be non-zero, or Value error results. -RRGetMonitorModes +RRGetCrtcModes window: WINDOW + crtc-index: CRTC -> - root: WINDOW - monitors: LISTofMONITORINFO - - where: - - MONITORINFO { - timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - x, y: INT16 - mode: MODEID - rotation: ROTATION - rotations: SETofROTATION - default-mode: MODEID - modes: LISTofMONITORMODE - } + timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + x, y: INT16 + mode: MODEID + rotation: ROTATION + rotations: SETofROTATION + default-mode: MODEID + modes: LISTofCRTCMODE Errors: Window - RRGetMonitorModes returns information about the current and available - configurations for all monitors connected to the screen associated - with 'window'. + RRGetCrtcModes returns information about the current and available + configurations for the specified crtc connected to the screen + associated with 'window'. - 'root' is the root window of the screen. - 'timestamp' indicates when the configuration was last set. 'config-timestamp' indicates when the screen configuration @@ -436,29 +474,32 @@ RRGetMonitorModes is using is up to date, to ensure clients can be well behaved in the face of race conditions. - 'x' and 'y' indicate the position of this monitor within the screen - region. They will be set to 0 when the monitor is disabled. + 'x' and 'y' indicate the position of this CRTC within the screen + region. They will be set to 0 when the CRTC is disabled. - 'mode' indicates which mode is active, or 'Disabled' indicating - that the monitor has been disabled and is not displaying the screen + 'mode' indicates which mode is active, or Disabled 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 monitor is disabled. + when the CRTC is disabled. 'rotations' contains the set of rotations and reflections supported - by the monitor. + by the CRTC. - 'default-mode' is the mode the monitor is set to at server + 'default-mode' is the mode the CRTC is set to at server reset time. 'modes' is the list of possible displayed modes. Within each mode, the sizes are reported for rotation set to Rotate_0. -RRAddMonitorMode +RRGetOutputs window: WINDOW - monitor-index: MONITOR - mode: MONITORMODE + +RRAddCrtcMode + window: WINDOW + crtc-index: CRTC + mode: CRTCMODE config-timestamp: TIMESTAMP timestamp: TIMESTAMP @@ -466,44 +507,45 @@ RRAddMonitorMode Errors: Window, Value, Match, Name - 'window' and 'monitor-index' indicate which monitor is to be - configured. If 'monitor-index' is out of range, a Value error is + 'window' and 'crtc-index' indicate which CRTC is to be + configured. If 'crtc-index' is out of range, a Value error is returned. - 'mode' provides a new mode for the monitor. If the name of 'mode' + 'mode' provides a new mode for the CRTC. If the name of 'mode' names an existing mode, a Name error is returned. If 'mode' cannot be - supported by the specified monitor, a Match error is returned. If + supported by the specified CRTC, a Match error is returned. If some parameter of the mode is not valid in some other way, a Value error is returned. - This request generates MonitorChangeNotify events. + This request generates CrtcChangeNotify events. -RRDeleteMonitorMode +RRDeleteCrtcMode window: WINDOW - monitor-index: MONITOR + crtc-index: CRTC name: STRING -> Errors: Window, Value, Name - 'window' and 'monitor-index' indicate which monitor is to be - configured. If 'monitor-index' is out of range, a Value error is + 'window' and 'crtc-index' indicate which CRTC is to be + configured. If 'crtc-index' is out of range, a Value error is returned. 'name' specifies which mode to delete. If no mode of the specified name exists, a Name error is returned. The named mode must have - been added with RRAddMonitorMode, else an Access error is returned. + been added with RRAddCrtcMode, else an Access error is returned. The named mode must not be active, else a Match error is returned. -RRSetMonitorMode +RRSetCrtcConfig window: WINDOW - monitor-index: MONITOR + crtc-index: CRTC timestamp: TIMESTAMP config-timestamp: TIMESTAMP x, y: INT16 mode: MODEID rotation: ROTATION + outputs: LISTofOUTPUT -> @@ -511,7 +553,7 @@ RRSetMonitorMode new-timestamp: TIMESTAMP config-timestamp: TIMESTAMP root: WINDOW - monitor: MONITOR + monitor: CRTC subpixelOrder: SUBPIXELORDER Errors: Value, Match @@ -522,7 +564,7 @@ RRSetMonitorMode 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 + 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 @@ -541,6 +583,10 @@ RRSetMonitorMode 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. + This request may fail for other indeterminate reasons, in which case 'status' will be set to Failed and no configuration change will be made. @@ -571,7 +617,7 @@ RRSetMonitorMode 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 +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. @@ -596,14 +642,14 @@ RRScreenChangeNotify 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 + 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 + 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 @@ -613,21 +659,21 @@ RRScreenChangeNotify 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 + selected for notification. This is to prevent a common race that might occur on log-in, where many applications start up just at the time when a display manager or log in script might be changing the screen size or configuration. 8.1 Events added in version 1.2 of the RandR extension -RRMonitorChangeNotify +RRCrtcChangeNotify sequenceNumber: CARD16 low 16 bits of request's seq. number timestamp: TIMESTAMP time monitor was changed configTimestamp: TIMESTAMP time config data was changed root: WINDOW root window of screen window: WINDOW window requesting notification - monitor-index: MONITOR monitor which changed + crtc-index: CRTC monitor which changed mode: MODEID new mode rotation: ROTATION; new rotation subpixelOrder: SUBPIXELORDER order of subpixels @@ -636,24 +682,24 @@ RRMonitorChangeNotify This event is generated whenever the monitor configuration is changed and sent to requesting clients. 'timestamp' indicates when the - monitor configuration was changed. 'configTimestamp' says when the + monitor configuration was changed. 'configTimestamp' says when the last time the configuration was changed. 'root' is the root of the screen the change occurred on, 'window' is window selecting for this event. 'size-id' contains the index of the current size. This event is sent whenever the monitor's configuration changes or if a new monitor configuration becomes available that was - not available in the past. In this case (config-timestamp in + 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 RRGetMonitorModes), the client MUST call - RRGetMonitorModes to update its view of possible monitor + 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 + 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. @@ -661,22 +707,22 @@ RRMonitorChangeNotify 9. Extension Versioning The RandR extension was developed in parallel with the implementation -to ensure the feasibility of various portions of the design. As +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 +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 + 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 + 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. @@ -686,10 +732,10 @@ list of what each version before 1.0 implemented: 1.2: Separate out screens from monitors, switch to full VESA modes Compatibility between 0.0 and 1.0 was *NOT* preserved, and 0.0 clients -will fail against 1.0 servers. The wire encoding op-codes were +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 +graceful way. Version 1.1 servers and clients are cross compatible with +1.0. Version 1.1 is considered to be stable and we intend upward compatibility from this point. 10. Relationship with other extensions @@ -750,7 +796,7 @@ A.1 Common Types RRSELECTMASK 0x0001 ScreenChangeNotifyMask - 0x0002 MonitorChangeNotifyMask Added in version 1.2 + 0x0002 CrtcChangeNotifyMask Added in version 1.2 RRCONFIGSTATUS 0x0 Success @@ -761,7 +807,7 @@ A.1 Common Types SIZEID 0xffff Disabled - MONITORMODE (36) Added in version 1.2 + CRTCMODE (36) Added in version 1.2 2 CARD16 width in pixels 2 CARD16 height in pixels 4 CARD32 width in millimeters @@ -910,7 +956,7 @@ A.2.1 Protocol Requests added with version 1.2 4 CARD32 height in millimeters - RRGetMonitorModes + RRGetCrtcInfo 1 CARD8 major opcode 1 0x08 RandR opcode @@ -922,16 +968,16 @@ A.2.1 Protocol Requests added with version 1.2 2 CARD16 sequence number 4 i*6 + m*9 + (b+p)/4 reply length 4 WINDOW root - 2 CARD16 i = number of MONITORINFO following - 2 CARD16 m = number of SIZE following + 2 CARD16 i = number of CRTCINFO following + 2 CARD16 m = number of CRTCMODE following 2 CARD16 b = size of name array following 14 unused - i*24 LISTofMONITORINFO one per monitor - m*36 LISTofMONITORMODE for all monitors - b LISTofCARD* list of mode names + i*24 LISTofCRTCINFO one per monitor + m*36 LISTofCRTCMODE for all monitors + b LISTofCARD8 list of mode names p pad pad(b) - MONITORINFO + CRTCINFO 4 TIMESTAMP timestamp 4 TIMESTAMP config-timestamp 2 INT16 x @@ -940,31 +986,31 @@ A.2.1 Protocol Requests added with version 1.2 2 MODEID mode 2 MODEID default mode 2 SETofROTATION rotations - 2 CARD16 start offset in LISTofMONITORMODE - 2 CARD16 number of MONITORMODE + 2 CARD16 start offset in LISTofCRTCMODE + 2 CARD16 number of CRTCMODE - RRAddMonitorMode + RRAddCrtcMode 1 CARD8 major opcode 1 0x09 RandR opcode 2 12+(b+p)/4 length 4 WINDOW window - 2 MONITOR monitor index + 2 CRTC monitor index 2 unused - 36 MONITORMODE mode + 36 CRTCMODE mode b STRING mode name p pad(b) - RRDeleteMonitorMode + RRDeleteCrtcMode 1 CARD8 major opcode 1 0x0a RandR opcode 2 3+(b+p)/4 length 4 WINDOW window - 2 MONITOR monitor index + 2 CRTC monitor index 2 CARD16 mode name length b STRING mode name p pad(b) - RRSetMonitorMode + RRSetCrtcConfig 1 CARD8 major opcode 1 0x0b RandR opcode @@ -972,7 +1018,7 @@ A.2.1 Protocol Requests added with version 1.2 4 WINDOW window 4 TIMESTAMP timestamp 4 TIMESTAMP config timestamp - 2 MONITOR monitor index + 2 CRTC monitor index 2 INT16 x 2 INT16 y 2 MODEID mode index @@ -987,7 +1033,7 @@ A.2.1 Protocol Requests added with version 1.2 4 TIMESTAMP new configuration timestamp 4 WINDOW root 2 SUBPIXELORDER subpixel order defined in Render - 2 MONITOR monitor + 2 CRTC monitor 8 unused @@ -1011,7 +1057,7 @@ A.3 Protocol Events A.3.1 Protocol Events added with version 1.2 - RRMonitorChangeNotify + RRCrtcChangeNotify 1 Base + 1 code 1 0 sub-code @@ -1020,7 +1066,7 @@ A.3.1 Protocol Events added with version 1.2 4 TIMESTAMP configuration timestamp 4 WINDOW root window 4 WINDOW request window - 2 MONITOR monitor index + 2 CRTC monitor index 2 MODEID mode ID 2 ROTATION new rotation and reflection 2 SUBPIXELORDER new subpixel order -- cgit v1.2.1 From dd19f8fbfcc4b8863347ce422006715ed95a7c00 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Mon, 11 Sep 2006 22:19:28 -0700 Subject: Move supported mode list from CRTC to OUTPUT. --- randrproto.txt | 381 +++++++++++++++++++++++++++++++-------------------------- 1 file changed, 206 insertions(+), 175 deletions(-) diff --git a/randrproto.txt b/randrproto.txt index 6c4e2d6..67179f0 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -89,18 +89,18 @@ Additional requests and events are provided for this new functionality. │ ┃ ┃ ║ ║ │ ┗━━━━━━━━━━━━━━━━━━━┫ ║ C ║ └───────────────────────┘ ║ ║ - ┌──────┐ ┏━━━━┓ ╔═══════╗ ║ ║ - │screen│ ┃CRTC┃ ║monitor║ ╚═══════════════════╝ - └──────┘ ┗━━━━┛ ╚═══════╝ + ┌──────┐ ┏━━━━┓ ╔══════╗ ║ ║ + │screen│ ┃CRTC┃ ║output║ ╚═══════════════════╝ + └──────┘ ┗━━━━┛ ╚══════╝ In this picture, the screen is covered (incompletely) by two CRTCs. CRTC1 -is connected to two monitors, A and B. CRTC2 is connected to monitor C. -Monitors A and B will present exactly the same region of the screen using -the same mode line. Monitor C will present a different (larger) region of +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 monitor; the -connection between CRTC and monitor is under application control, although +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. @@ -126,53 +126,51 @@ 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, 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). +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 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). +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. +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 @@ -180,18 +178,17 @@ There are no new error types defined by this extension. 5. Protocol Types -RRCONFIGSTATUS { - Success - InvalidConfigTime - InvalidTime - Failed } -ROTATION { - Rotate_0 - Rotate_90 - Rotate_180 - Rotate_270 - Reflect_X - Reflect_Y } +RRCONFIGSTATUS { Success + InvalidConfigTime + InvalidTime + Failed } + +ROTATION { Rotate_0 + Rotate_90 + Rotate_180 + Rotate_270 + Reflect_X + Reflect_Y } RRSELECTMASK { RRScreenChangeNotifyMask RRCrtcChangeNotifyMask (New in version 1.2) @@ -199,48 +196,41 @@ RRSELECTMASK { RRScreenChangeNotifyMask SIZEID { CARD16 } -MODEID { CARD16 or Disabled } +MODE { XID or None } CRTC { CARD16 } OUTPUT { CARD16 } SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render - SubPixelHorizontalRGB extensions definitions; they are here - SubPixelHorizontalBGR only for convenience. - SubPixelVerticalRGB - SubPixelVerticalBGR - SubPixelNone } - -SCREENSIZE { - widthInPixels, heightInPixels: CARD16 - widthInMillimeters, heightInMillimeters: CARD16 } - -MODEFLAG { - hsync_positive hsync_negative - vsync_positive vsync_negative - interlace double_scan - csync csync_positive csync_negative - hskew_present - bcast - pixel_multiplex - double_clock - clock_divide_by_2 -} - -CRTCMODE { - name: STRING - widthInPixels, heightInPixels: CARD16 - widthInMillimeters, heightInMillimeters: CARD32 - dotClock: CARD32 - hSyncStart, hSyncEnd, hTotal, hSkew: CARD16 - vSyncStart, vSyncEnd, vTotal: CARD16 - modeFlags: SETofMODEFLAG - possible-outputs: LISTofLISTofOUTPUT -} - -REFRESH { - rates: LISTofCARD16 } + SubPixelHorizontalRGB extensions definitions; they are here + SubPixelHorizontalBGR only for convenience. + SubPixelVerticalRGB + SubPixelVerticalBGR + SubPixelNone } + +SCREENSIZE { widthInPixels, heightInPixels: CARD16 + widthInMillimeters, heightInMillimeters: CARD16 } + +MODEFLAG { hsync_positive hsync_negative + vsync_positive vsync_negative + interlace double_scan + csync csync_positive csync_negative + hskew_present + bcast + pixel_multiplex + double_clock + clock_divide_by_2 } + +OUTPUTMODE { id: MODE + widthInPixels, heightInPixels: CARD16 + widthInMillimeters, heightInMillimeters: CARD32 + dotClock: CARD32 + hSyncStart, hSyncEnd, hTotal, hSkew: CARD16 + vSyncStart, vSyncEnd, vTotal: CARD16 + modeFlags: SETofMODEFLAG } + +REFRESH { rates: LISTofCARD16 } 6. Extension Initialization @@ -249,7 +239,9 @@ The name of this extension is "RANDR". RRQueryVersion client-major-version: CARD32 client-minor-version: CARD32 - -> + + ▶ + major-version: CARD32 minor-version: CARD32 @@ -300,7 +292,7 @@ RRSetScreenConfig rotation: ROTATION rate: CARD16 - -> + ▶ status: RRCONFIGSTATUS new-timestamp: TIMESTAMP @@ -353,7 +345,7 @@ RRSetScreenConfig RRGetScreenInfo window: WINDOW - -> + ▶ rotations: SETofROTATION root: WINDOW @@ -406,17 +398,17 @@ RRGetScreenInfo 7.1. Extension Requests added in version 1.2 of the extension As introduced above, version 1.2 of the extension splits the screen size -from the monitor configuration, permitting the subset of the screen -presented by multiple monitors to be configured. As a separate notion, the +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 monitors are added and removed from the system, the set returned -by RRGetMonitorModes will change so that applications can detect dynamic -changes in the monitor environment. +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 @@ -445,20 +437,47 @@ RRSetScreenSize extension and the core protocol. They must be non-zero, or Value error results. -RRGetCrtcModes +RRGetScreenResources + window: WINDOW + + ▶ + + timestamp: TIMESTAMP + config-timestamp: TIMESTAMP + number-of-crtcs: CARD16 + number-of-outputs: CARD16 + + Errors: Window + +RRGetOutputInfo window: WINDOW - crtc-index: CRTC + output: OUTPUT - -> + ▶ timestamp: TIMESTAMP config-timestamp: TIMESTAMP + name: STRING + crtc: CRTC + crtcs: LISTofCRTC + clones: LISTofOUTPUT + modes: LISTofOUTPUTMODE + +RRGetCrtcInfo + window: WINDOW + crtc: CRTC + + ▶ + + timestamp: TIMESTAMP x, y: INT16 - mode: MODEID + mode: MODE rotation: ROTATION + + config-timestamp: TIMESTAMP rotations: SETofROTATION - default-mode: MODEID - modes: LISTofCRTCMODE + default-mode: MODE + outputs: LISTofOUTPUT Errors: Window @@ -468,12 +487,6 @@ RRGetCrtcModes 'timestamp' indicates when the configuration was last set. - 'config-timestamp' indicates when the screen configuration - information last changed: requests to set the screen will fail - unless the timestamp indicates that the information the client - is using is up to date, to ensure clients can be well behaved - in the face of race conditions. - 'x' and 'y' indicate the position of this CRTC within the screen region. They will be set to 0 when the CRTC is disabled. @@ -484,70 +497,68 @@ RRGetCrtcModes 'rotation' indicates the active rotation. It is set to Rotate_0 when the CRTC is disabled. + 'config-timestamp' indicates when the configuration information last + changed: requests to configure the CRTC 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. + 'rotations' contains the set of rotations and reflections supported by the CRTC. 'default-mode' is the mode the CRTC is set to at server reset time. - 'modes' is the list of possible displayed modes. Within each mode, - the sizes are reported for rotation set to Rotate_0. - -RRGetOutputs +RRAddOutputMode window: WINDOW - -RRAddCrtcMode - window: WINDOW - crtc-index: CRTC - mode: CRTCMODE + output: OUTPUT + mode: OUTPUTMODE config-timestamp: TIMESTAMP timestamp: TIMESTAMP - -> + ▶ Errors: Window, Value, Match, Name - 'window' and 'crtc-index' indicate which CRTC is to be - configured. If 'crtc-index' is out of range, a Value error is - returned. + 'window' and 'output' which output is to be configured. If 'output' + is out of range, a Value error is returned. - 'mode' provides a new mode for the CRTC. If the name of 'mode' + 'mode' provides a new mode for the output. If the name of 'mode' names an existing mode, a Name error is returned. If 'mode' cannot be - supported by the specified CRTC, a Match error is returned. If - some parameter of the mode is not valid in some other way, a Value - error is returned. + supported by the specified output, a Match error is returned. If some + parameter of the mode is not valid in some other way, a Value error + is returned. - This request generates CrtcChangeNotify events. + This request generates OutputChangeNotify events. -RRDeleteCrtcMode +RRDeleteOutputMode window: WINDOW - crtc-index: CRTC + output: OUTPUT name: STRING - -> + ▶ Errors: Window, Value, Name - 'window' and 'crtc-index' indicate which CRTC is to be - configured. If 'crtc-index' is out of range, a Value error is - returned. + 'window' and 'output' indicate which output is to be configured. If + 'output' is out of range, a Value error is returned. 'name' specifies which mode to delete. If no mode of the specified - name exists, a Name error is returned. The named mode must have - been added with RRAddCrtcMode, else an Access error is returned. - The named mode must not be active, else a Match error is returned. + name exists, a Name error is returned. The named mode must have been + added with RRAddOutputMode, else an Access error is returned. The + named mode must not be active, else a Match error is returned. RRSetCrtcConfig window: WINDOW - crtc-index: CRTC + crtc: CRTC timestamp: TIMESTAMP config-timestamp: TIMESTAMP x, y: INT16 - mode: MODEID + mode: MODE rotation: ROTATION outputs: LISTofOUTPUT - -> + ▶ status: RRCONFIGSTATUS new-timestamp: TIMESTAMP @@ -574,9 +585,10 @@ RRSetCrtcConfig monitor's content. 'x' and 'y' must be within the screen size, else a Value error results. - 'mode' contains the index of desired mode or Disabled indicating the - monitor should be disabled. If 'mode' is not one of these values, a - Value error results. + '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 @@ -585,19 +597,23 @@ RRSetCrtcConfig '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. + sets for this CRTC or a Match error results. + + If 'mode' is None, then 'outputs' must be empty, else a Match error + results. Conversly, 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 monitor to the specified position, mode, - rotation and reflection. The entire area of the monitor must fit - within the screen size, else a Match error results. As an example, - rotating the screen so that a single monitor fills the entire screen - before and after may necessitate disabling the monitor, resizing the - screen, then re-enabling the monitor at the new configuration to - avoid an invalid intermediate configuration. + 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. @@ -633,7 +649,7 @@ RRScreenChangeNotify 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 + size-id: SIZEID index of new size subpixelOrder: SUBPIXELORDER order of subpixels widthInPixels: CARD16 heightInPixels: CARD16 @@ -666,15 +682,30 @@ RRScreenChangeNotify 8.1 Events added in version 1.2 of the RandR extension +RROutputChangeNotify: + sequence-number: CARD16 low 16 bits of request's seq. number + timestamp: TIMESTAMP time screen was reconfigured + config-timestamp: TIMESTAMP time available config data was changed + root: WINDOW root window of screen + window: WINDOW window requesting notification + output: OUTPUT output which changed + + 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. + RRCrtcChangeNotify - sequenceNumber: CARD16 low 16 bits of request's seq. number + sequence-number: CARD16 low 16 bits of request's seq. number timestamp: TIMESTAMP time monitor was changed - configTimestamp: TIMESTAMP time config data was changed + config-timestamp: TIMESTAMP time config data was changed root: WINDOW root window of screen window: WINDOW window requesting notification crtc-index: CRTC monitor which changed - mode: MODEID new mode + mode: MODE new mode rotation: ROTATION; new rotation subpixelOrder: SUBPIXELORDER order of subpixels x: INT16 x position of monitor within screen @@ -682,7 +713,7 @@ RRCrtcChangeNotify This event is generated whenever the monitor configuration is changed and sent to requesting clients. 'timestamp' indicates when the - monitor configuration was changed. 'configTimestamp' says when the + monitor 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. 'size-id' contains the index of the current size. @@ -845,7 +876,7 @@ errors if used in version 1.0. 2 3 length 4 CARD32 major version 4 CARD32 minor version - -> + ▶ 1 1 Reply 1 unused 2 CARD16 sequence number @@ -866,7 +897,7 @@ errors if used in version 1.0. 2 ROTATION rotation/reflection 2 CARD16 refresh rate (1.1 only) 2 CARD16 pad - -> + ▶ 1 1 Reply 1 RRCONFIGSTATUS status 2 CARD16 sequence number @@ -896,7 +927,7 @@ errors if used in version 1.0. 1 0x05 RandR opcode 2 2 length 4 WINDOW window - -> + ▶ 1 1 Reply 1 CARD8 set of Rotations 2 CARD16 sequence number @@ -929,7 +960,7 @@ A.2.1 Protocol Requests added with version 1.2 1 0x06 RandR opcode 2 2 length 4 WINDOW window - -> + ▶ 1 1 Reply 1 unused 2 CARD16 sequence number @@ -962,7 +993,7 @@ A.2.1 Protocol Requests added with version 1.2 1 0x08 RandR opcode 2 2 length 4 WINDOW window - -> + ▶ 1 1 Reply 1 unused 2 CARD16 sequence number @@ -983,8 +1014,8 @@ A.2.1 Protocol Requests added with version 1.2 2 INT16 x 2 INT16 y 2 ROTATION rotation - 2 MODEID mode - 2 MODEID default mode + 2 MODE mode + 2 MODE default mode 2 SETofROTATION rotations 2 CARD16 start offset in LISTofCRTCMODE 2 CARD16 number of CRTCMODE @@ -1021,10 +1052,10 @@ A.2.1 Protocol Requests added with version 1.2 2 CRTC monitor index 2 INT16 x 2 INT16 y - 2 MODEID mode index + 2 MODE mode index 2 ROTATION rotation/reflection 2 unused - -> + ▶ 1 1 Reply 1 RRCONFIGSTATUS status 2 CARD16 sequence number @@ -1067,7 +1098,7 @@ A.3.1 Protocol Events added with version 1.2 4 WINDOW root window 4 WINDOW request window 2 CRTC monitor index - 2 MODEID mode ID + 2 MODE mode ID 2 ROTATION new rotation and reflection 2 SUBPIXELORDER new subpixel order 2 INT16 x -- cgit v1.2.1 From 4e47d7af0574690dcf00516337bf0bbe567c9c75 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Mon, 11 Sep 2006 22:49:15 -0700 Subject: Finish basic request descriptions for version 1.2 outputs now report list of valid modes. crtcs accept a valid mode which must be supported on all connected outputs. outputs also report connection status. --- randrproto.txt | 112 +++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 86 insertions(+), 26 deletions(-) diff --git a/randrproto.txt b/randrproto.txt index 67179f0..6206e4c 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -1,17 +1,17 @@ - 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 + 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 @@ -202,6 +202,8 @@ CRTC { CARD16 } OUTPUT { CARD16 } +CONNECTION { Connected, Disconnected, UnknownConnection } + SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render SubPixelHorizontalRGB extensions definitions; they are here SubPixelHorizontalBGR only for convenience. @@ -395,6 +397,8 @@ RRGetScreenInfo 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 @@ -449,6 +453,21 @@ RRGetScreenResources Errors: Window + RRGetScreenResources returns information about the number 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. + + 'number-of-crtcs' indicates the valid range of CRTC indices. + + 'number-of-outputs' indicates the valid range of OUTPUT indices. + RRGetOutputInfo window: WINDOW output: OUTPUT @@ -456,13 +475,53 @@ RRGetOutputInfo ▶ timestamp: TIMESTAMP + crtc: CRTC + config-timestamp: TIMESTAMP name: STRING - crtc: CRTC + connection: CONNECTION crtcs: LISTofCRTC clones: LISTofOUTPUT modes: LISTofOUTPUTMODE + Errors: Window + + RRGetOutputInfo returns information about the current and available + configurations for the specified output connected to the screen + associated with 'window'. + + '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. + + '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. + + '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. + + '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. + RRGetCrtcInfo window: WINDOW crtc: CRTC @@ -498,7 +557,7 @@ RRGetCrtcInfo when the CRTC is disabled. 'config-timestamp' indicates when the configuration information last - changed: requests to configure the CRTC will fail unless the + changed. Requests to configure the CRTC 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. @@ -512,9 +571,9 @@ RRGetCrtcInfo RRAddOutputMode window: WINDOW output: OUTPUT - mode: OUTPUTMODE config-timestamp: TIMESTAMP timestamp: TIMESTAMP + mode: OUTPUTMODE ▶ @@ -688,35 +747,36 @@ RROutputChangeNotify: config-timestamp: TIMESTAMP time available config data was changed root: WINDOW root window of screen window: WINDOW window requesting notification - output: OUTPUT output which changed 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. + occurred on, 'window' is window selecting for this event. The + precise change can be detected by examining the new state of the + system. -RRCrtcChangeNotify +RRCrtcChangeNotify /* XXX need to fit to 32 bytes */ sequence-number: CARD16 low 16 bits of request's seq. number 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-index: CRTC monitor which changed + crtc: CRTC CRTC which changed mode: MODE new mode rotation: ROTATION; new rotation subpixelOrder: SUBPIXELORDER order of subpixels - x: INT16 x position of monitor within screen - y: INT16 y position of monitor within screen + x: INT16 x position of CRTC within screen + y: INT16 y position of CRTC within screen - This event is generated whenever the monitor configuration is changed + This event is generated whenever the CRTC configuration is changed and sent to requesting clients. 'timestamp' indicates when the - monitor configuration was changed. 'config-timestamp' says 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. 'size-id' contains the index of the current size. + event. This event is sent whenever the monitor's configuration changes or if a new monitor configuration becomes available that was -- cgit v1.2.1 From e81693720d5d1acf31780de3f5fa90bf0f46a801 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Tue, 12 Sep 2006 16:48:22 -0700 Subject: Rearrange modes to be listed with screen resources. Encoding. Modes are now listed as screen resources instead of with the output; they're shared across outputs for cloning. Wrote up encoding. --- randrproto.txt | 596 +++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 367 insertions(+), 229 deletions(-) diff --git a/randrproto.txt b/randrproto.txt index 6206e4c..7861bcf 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -110,7 +110,7 @@ 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. -2. Acknowlegements +1.1 Acknowlegements Our thanks to the contributors to the design found on the xpert mailing list, in particular: @@ -124,6 +124,8 @@ Thomas Winischhofer for the hardware-accelerated SiS rotation implementation Matthew Tippet 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 @@ -166,15 +168,28 @@ 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. +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 @@ -198,9 +213,9 @@ SIZEID { CARD16 } MODE { XID or None } -CRTC { CARD16 } +CRTC { XID } -OUTPUT { CARD16 } +OUTPUT { XID } CONNECTION { Connected, Disconnected, UnknownConnection } @@ -224,16 +239,19 @@ MODEFLAG { hsync_positive hsync_negative double_clock clock_divide_by_2 } -OUTPUTMODE { id: MODE - widthInPixels, heightInPixels: CARD16 - widthInMillimeters, heightInMillimeters: CARD32 - dotClock: CARD32 - hSyncStart, hSyncEnd, hTotal, hSkew: CARD16 - vSyncStart, vSyncEnd, vTotal: CARD16 - modeFlags: SETofMODEFLAG } +MODEINFO { id: MODE + name: STRING + widthInPixels, heightInPixels: CARD16 + widthInMillimeters, heightInMillimeters: CARD32 + dotClock: CARD32 + hSyncStart, hSyncEnd, hTotal, hSkew: CARD16 + vSyncStart, vSyncEnd, vTotal: CARD16 + modeFlags: SETofMODEFLAG } REFRESH { rates: LISTofCARD16 } + ❧❧❧❧❧❧❧❧❧❧❧ + 6. Extension Initialization The name of this extension is "RANDR". @@ -255,6 +273,8 @@ RRQueryVersion It is the clients responsibility to ensure that the server supports a version which is compatible with its expectations. + ❧❧❧❧❧❧❧❧❧❧❧ + 7. Extension Requests RRSelectInput @@ -344,11 +364,10 @@ RRSetScreenConfig Value errors are generated when 'rotation', 'rate' or 'size-id' are invalid. -RRGetScreenInfo +┌─── + RRGetScreenInfo window: WINDOW - - ▶ - + ▶ rotations: SETofROTATION root: WINDOW timestamp: TIMESTAMP @@ -358,8 +377,7 @@ RRGetScreenInfo rate: CARD16 sizes: LISTofSCREENSIZE refresh: LISTofREFRESH - - where: +└─── Errors: Window @@ -397,8 +415,6 @@ RRGetScreenInfo 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 @@ -409,26 +425,28 @@ 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 +┌─── + 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 +┌─── + 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 @@ -441,20 +459,20 @@ RRSetScreenSize extension and the core protocol. They must be non-zero, or Value error results. -RRGetScreenResources +┌─── + RRGetScreenResources window: WINDOW - - ▶ - + ▶ timestamp: TIMESTAMP config-timestamp: TIMESTAMP - number-of-crtcs: CARD16 - number-of-outputs: CARD16 - + crtcs: LISTofCRTC + outputs: LISTofOUTPUT + modes: LISTofMODEINFO +└─── Errors: Window - RRGetScreenResources returns information about the number of outputs - and crtcs connected to the screen associated with 'window'. + RRGetScreenResources returns the list of outputs and crtcs connected + to the screen associated with 'window'. 'timestamp' indicates when the configuration was last set. @@ -464,43 +482,49 @@ RRGetScreenResources to date, to ensure clients can be well behaved in the face of race conditions. - 'number-of-crtcs' indicates the valid range of CRTC indices. + 'crtcs' contains the list of CRTCs associated with the screen. - 'number-of-outputs' indicates the valid range of OUTPUT indices. + 'outputs' contains the list of outputs associated with the screen. -RRGetOutputInfo - window: WINDOW + '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 - config-timestamp: TIMESTAMP name: STRING connection: CONNECTION crtcs: LISTofCRTC clones: LISTofOUTPUT - modes: LISTofOUTPUTMODE + modes: LISTofMODE +└─── - Errors: Window + Errors: Output, RRGetOutputInfo returns information about the current and available - configurations for the specified output connected to the screen - associated with 'window'. + 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. - '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. - '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". @@ -522,21 +546,78 @@ RRGetOutputInfo connect this output to a CRTC not using one of these modes results in a Match error. -RRGetCrtcInfo - window: WINDOW - crtc: CRTC +┌─── + 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 - config-timestamp: TIMESTAMP rotations: SETofROTATION - default-mode: MODE - outputs: LISTofOUTPUT + possible-outputs: LISTofOUTPUT +└─── Errors: Window @@ -544,71 +625,36 @@ RRGetCrtcInfo 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 Disabled indicating - that the CRTC has been disabled and is not displaying the screen - contents. + '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. - 'config-timestamp' indicates when the configuration information last - changed. Requests to configure the CRTC 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. - + '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. - 'default-mode' is the mode the CRTC is set to at server - reset time. + 'possible-outputs' lists all of the outputs which may be connected + to this CRTC. -RRAddOutputMode - window: WINDOW - output: OUTPUT - config-timestamp: TIMESTAMP - timestamp: TIMESTAMP - mode: OUTPUTMODE - - ▶ - - Errors: Window, Value, Match, Name - - 'window' and 'output' which output is to be configured. If 'output' - is out of range, a Value error is returned. - - 'mode' provides a new mode for the output. If the name of 'mode' - names an existing mode, a Name error is returned. If 'mode' cannot be - supported by the specified output, a Match error is returned. If some - parameter of the mode is not valid in some other way, a Value error - is returned. - - This request generates OutputChangeNotify events. - -RRDeleteOutputMode - window: WINDOW - output: OUTPUT - name: STRING - - ▶ - - Errors: Window, Value, Name - - 'window' and 'output' indicate which output is to be configured. If - 'output' is out of range, a Value error is returned. - - 'name' specifies which mode to delete. If no mode of the specified - name exists, a Name error is returned. The named mode must have been - added with RRAddOutputMode, else an Access error is returned. The - named mode must not be active, else a Match error is returned. - -RRSetCrtcConfig - window: WINDOW +┌─── + RRSetCrtcConfig crtc: CRTC timestamp: TIMESTAMP config-timestamp: TIMESTAMP @@ -616,16 +662,11 @@ RRSetCrtcConfig mode: MODE rotation: ROTATION outputs: LISTofOUTPUT - - ▶ - + ▶ status: RRCONFIGSTATUS new-timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - root: WINDOW - monitor: CRTC subpixelOrder: SUBPIXELORDER - +└─── Errors: Value, Match If 'timestamp' is less than the time when the configuration was last @@ -680,15 +721,11 @@ RRSetCrtcConfig '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 monitor to allow correct subpixel rendering. + ❧❧❧❧❧❧❧❧❧❧❧ + 8. Extension Events Clients MAY select for ConfigureNotify on the root window to be @@ -700,7 +737,8 @@ 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 +┌─── + RRScreenChangeNotify rotation: ROTATION; new rotation sequenceNumber: CARD16 low 16 bits of request's seq. number @@ -714,7 +752,7 @@ RRScreenChangeNotify 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 @@ -741,12 +779,17 @@ RRScreenChangeNotify 8.1 Events added in version 1.2 of the RandR extension -RROutputChangeNotify: +┌─── + RROutputChangeNotify: sequence-number: CARD16 low 16 bits of request's seq. number timestamp: TIMESTAMP time screen was reconfigured config-timestamp: TIMESTAMP time available config data was changed - root: WINDOW root window of screen 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' @@ -757,8 +800,8 @@ RROutputChangeNotify: precise change can be detected by examining the new state of the system. -RRCrtcChangeNotify /* XXX need to fit to 32 bytes */ - +┌─── + RRCrtcChangeNotify /* XXX need to fit to 32 bytes */ sequence-number: CARD16 low 16 bits of request's seq. number timestamp: TIMESTAMP time monitor was changed config-timestamp: TIMESTAMP time config data was changed @@ -770,7 +813,7 @@ RRCrtcChangeNotify /* XXX need to fit to 32 bytes */ subpixelOrder: SUBPIXELORDER order of subpixels 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 @@ -795,6 +838,8 @@ RRCrtcChangeNotify /* XXX need to fit to 32 bytes */ 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 @@ -820,7 +865,8 @@ list of what each version before 1.0 implemented: 1.1: Added refresh rates - 1.2: Separate out screens from monitors, switch to full VESA modes + 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 @@ -829,6 +875,8 @@ graceful way. Version 1.1 servers and clients are cross compatible with 1.0. Version 1.1 is considered to be stable and we intend upward compatibility from this point. + ❧❧❧❧❧❧❧❧❧❧❧ + 10. Relationship with other extensions Two other extensions have a direct relationship with this extension. This @@ -866,6 +914,8 @@ 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 @@ -876,29 +926,38 @@ protocol encoding document. A.1 Common Types - ROTATION +┌─── + 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 +┌─── + RRSELECTMASK 0x0001 ScreenChangeNotifyMask 0x0002 CrtcChangeNotifyMask Added in version 1.2 - - RRCONFIGSTATUS + 0x0004 OutputChangeNotifyMask 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. - SIZEID - 0xffff Disabled - - CRTCMODE (36) Added in version 1.2 +┌─── + MODEINFO (40) Added in version 1.2 + 4 CARD32 id 2 CARD16 width in pixels 2 CARD16 height in pixels 4 CARD32 width in millimeters @@ -911,41 +970,41 @@ A.1 Common Types 2 CARD16 v sync start 2 CARD16 v sync end 2 CARD16 v total - 2 CARD16 name length (n) + 2 CARD16 name length 4 SETofMODEFLAG mode flags +└─── - A monitor mode specifies the complete CRTC timings for + An output mode specifies the complete CRTC timings for a specfic 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 location of the name in the encoding is specified separately - A.2 Protocol Requests - Opcodes 0x1 and 0x3 were used in the 0.0 protocols, and will return errors if used in version 1.0. - RRQueryVersion +┌─── + RRQueryVersion 1 CARD8 major opcode - 1 0x01 RandR opcode + 1 0x00 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 +┌─── + RRSetScreenConfig 1 CARD8 major opcode 1 0x02 RandR opcode @@ -957,7 +1016,7 @@ errors if used in version 1.0. 2 ROTATION rotation/reflection 2 CARD16 refresh rate (1.1 only) 2 CARD16 pad - ▶ + ▶ 1 1 Reply 1 RRCONFIGSTATUS status 2 CARD16 sequence number @@ -969,9 +1028,10 @@ errors if used in version 1.0. 2 CARD16 pad4 4 CARD32 pad5 4 CARD32 pad6 - - - RRSelectInput +└─── + +┌─── + RRSelectInput 1 CARD8 major opcode 1 0x04 RandR opcode @@ -979,15 +1039,16 @@ errors if used in version 1.0. 4 WINDOW window 2 SETofRRSELECTMASK enable 2 CARD16 pad - - - RRGetScreenInfo +└─── + +┌─── + 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 @@ -1011,16 +1072,17 @@ errors if used in version 1.0. REFRESH 2 CARD16 number of rates (n) 2n CARD16 rates +└─── A.2.1 Protocol Requests added with version 1.2 - RRGetScreenSizeRange - +┌─── + RRGetScreenSizeRange 1 CARD8 major opcode 1 0x06 RandR opcode 2 2 length 4 WINDOW window - ▶ + ▶ 1 1 Reply 1 unused 2 CARD16 sequence number @@ -1033,10 +1095,10 @@ A.2.1 Protocol Requests added with version 1.2 4 unused 4 unused 4 unused +└─── - - RRSetScreenSize - +┌─── + RRSetScreenSize 1 CARD8 major opcode 1 0x07 RandR opcode 2 5 length @@ -1045,93 +1107,152 @@ A.2.1 Protocol Requests added with version 1.2 2 CARD16 height 4 CARD32 width in millimeters 4 CARD32 height in millimeters - +└─── - RRGetCrtcInfo - +┌─── + RRGetScreenResources 1 CARD8 major opcode 1 0x08 RandR opcode 2 2 length 4 WINDOW window - ▶ + ▶ 1 1 Reply 1 unused 2 CARD16 sequence number - 4 i*6 + m*9 + (b+p)/4 reply length - 4 WINDOW root - 2 CARD16 i = number of CRTCINFO following - 2 CARD16 m = number of CRTCMODE following - 2 CARD16 b = size of name array following - 14 unused - i*24 LISTofCRTCINFO one per monitor - m*36 LISTofCRTCMODE for all monitors - b LISTofCARD8 list of mode names - p pad pad(b) - - CRTCINFO + 4 c+o+10m+(b+p)/4 reply length 4 TIMESTAMP timestamp 4 TIMESTAMP config-timestamp - 2 INT16 x - 2 INT16 y - 2 ROTATION rotation - 2 MODE mode - 2 MODE default mode - 2 SETofROTATION rotations - 2 CARD16 start offset in LISTofCRTCMODE - 2 CARD16 number of CRTCMODE - - RRAddCrtcMode + 2 c number of CRTCs + 2 o number of outputs + 2 m number of modeinfos + 2 b total bytes in mode names + 10 unused + 4c LISTofCRTC crtcs + 4o LISTofOUTPUT outputs + 40m LISTofMODEINFO modeinfos + b STRING8 mode names + p unused, p=pad(b) +└─── + +┌─── + RRGetOutputInfo 1 CARD8 major opcode 1 0x09 RandR opcode - 2 12+(b+p)/4 length - 4 WINDOW window - 2 CRTC monitor index - 2 unused - 36 CRTCMODE mode - b STRING mode name - p pad(b) - - RRDeleteCrtcMode + 2 3 length + 4 OUTPUT output + 4 TIMESTAMP config-timestamp + ▶ + 1 1 Reply + 1 RRCONFIGSTATUS status + 2 CARD16 sequence number + 4 c+m+(n+p)/4 reply length + 4 TIMESTAMP timestamp + 4 CRTC current connected crtc + 1 CONNECTION connection + 1 unused + 2 c number of CRTCs + 2 m number of modes + 2 n length of name + 8 unused + 4c LISTofCRTC crtcs + 4m LISTofMODE modes + n STRING8 name + p unused, p=pad(n) +└─── + +┌─── + RRCreateMode 1 CARD8 major opcode - 1 0x0a RandR opcode - 2 3+(b+p)/4 length + 1 0x09 RandR opcode + 2 12+(n+p)/4 length 4 WINDOW window - 2 CRTC monitor index - 2 CARD16 mode name length - b STRING mode name - p pad(b) - - RRSetCrtcConfig - + 40 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 0x0b RandR opcode - 2 7 length - 4 WINDOW window + 1 0x09 RandR opcode + 2 2 length + 4 MODE mode +└─── +┌─── + RRAddOutputMode + 1 CARD8 major opcode + 1 0x09 RandR opcode + 2 3 length + 4 OUTPUT output + 4 MODE mode +└─── +┌─── + RRDeleteOutputMode + 1 CARD8 major opcode + 1 0x09 RandR opcode + 2 3 length + 4 OUTPUT output + 4 MODE mode +└─── +┌─── + RRGetCrtcInfo + 1 CARD8 major opcode + 1 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 + 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 + 4 unused + 4o LISTofOUTPUT outputs + 4p LISTofOUTPUT possible outputs +└─── +┌─── + RRSetCrtcConfig + 1 CARD8 major opcode + 1 RandR opcode + 2 7+n length + 4 CRTC crtc 4 TIMESTAMP timestamp 4 TIMESTAMP config timestamp - 2 CRTC monitor index 2 INT16 x 2 INT16 y - 2 MODE mode index + 4 MODE mode 2 ROTATION rotation/reflection - 2 unused - ▶ + 2 n number of outputs + 4n LISTofOUTPUT outputs + ▶ 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 CRTC monitor - 8 unused - + 2 SUBPIXELORDER subpixel order + 18 unused +└─── A.3 Protocol Events - RRScreenChangeNotify - +┌─── + RRScreenChangeNotify 1 Base + 0 code 1 ROTATION new rotation and reflection 2 CARD16 sequence number @@ -1145,24 +1266,41 @@ A.3 Protocol Events 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 - +┌─── + RROutputChangeNotify 1 Base + 1 code 1 0 sub-code 2 CARD16 sequence number 4 TIMESTAMP timestamp 4 TIMESTAMP configuration timestamp - 4 WINDOW root window 4 WINDOW request window - 2 CRTC monitor index - 2 MODE mode ID + 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 +└─── +┌─── + RRCrtcChangeNotify + 1 Base + 2 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 SUBPIXELORDER new subpixel order 2 INT16 x 2 INT16 y + 2 CARD16 width + 2 CARD16 height + 2 unused +└─── Bibliography -- cgit v1.2.1 From 1ec6ea06b8b7182b465e5c0d34475c20de76812b Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Tue, 12 Sep 2006 18:40:03 -0700 Subject: Spelling and formatting fixes. --- randrproto.txt | 79 +++++++++++++++++++++++++--------------------------------- 1 file changed, 34 insertions(+), 45 deletions(-) diff --git a/randrproto.txt b/randrproto.txt index 7861bcf..a252f36 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -35,7 +35,7 @@ These events include: 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 switchin implementation experience in the + ► 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 @@ -46,7 +46,7 @@ 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 +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 @@ -105,12 +105,12 @@ 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 togther to provide higher +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 Acknowlegements +1.1 Acknowledgements Our thanks to the contributors to the design found on the xpert mailing list, in particular: @@ -144,7 +144,7 @@ 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 +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 @@ -162,7 +162,7 @@ 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 +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 @@ -256,14 +256,14 @@ REFRESH { rates: LISTofCARD16 } The name of this extension is "RANDR". -RRQueryVersion +┌─── + 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 @@ -277,10 +277,11 @@ RRQueryVersion 7. Extension Requests -RRSelectInput +┌─── + RRSelectInput window: WINDOW enable: SETofRRSELECTMASK - +└─── Errors: Window, Value If 'enable' is RRScreenChangeNotifyMask, RRScreenChangeNotify events @@ -306,22 +307,21 @@ RRSelectInput when this request executes if the output configuration has changed since the client connected, to avoid race conditions. -RRSetScreenConfig +┌─── + 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 @@ -407,7 +407,7 @@ RRSetScreenConfig 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 + of 'sizes' has a corresponding element in 'refresh'. An empty list indicates no known rates, or a device for which refresh is not relevant. @@ -428,9 +428,7 @@ dynamic changes in the display environment. ┌─── RRGetScreenSizeRange window: WINDOW - ▶ - CARD16 minWidth, minHeight CARD16 maxWidth, maxHeight └─── @@ -509,8 +507,7 @@ dynamic changes in the display environment. clones: LISTofOUTPUT modes: LISTofMODE └─── - - Errors: Output, + Errors: Output RRGetOutputInfo returns information about the current and available configurations 'output'. @@ -700,7 +697,7 @@ dynamic changes in the display environment. sets for this CRTC or a Match error results. If 'mode' is None, then 'outputs' must be empty, else a Match error - results. Conversly, if 'mode' is not None, then 'outputs' must not be + 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 @@ -735,13 +732,13 @@ 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. +factors, such as re-cabling a monitor, etc. ┌─── RRScreenChangeNotify rotation: ROTATION; new rotation - sequenceNumber: CARD16 low 16 bits of request's seq. number + 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 @@ -781,7 +778,7 @@ factors, such as recabling a monitor, etc. ┌─── RROutputChangeNotify: - sequence-number: CARD16 low 16 bits of request's seq. number + sequence-number: CARD16 low 16 bits of request seq. number timestamp: TIMESTAMP time screen was reconfigured config-timestamp: TIMESTAMP time available config data was changed window: WINDOW window requesting notification @@ -802,7 +799,7 @@ factors, such as recabling a monitor, etc. ┌─── RRCrtcChangeNotify /* XXX need to fit to 32 bytes */ - sequence-number: CARD16 low 16 bits of request's seq. number + sequence-number: CARD16 low 16 bits of request seq. number timestamp: TIMESTAMP time monitor was changed config-timestamp: TIMESTAMP time config data was changed root: WINDOW root window of screen @@ -845,7 +842,7 @@ factors, such as recabling a monitor, etc. 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. +extension has changed to reflect the portions of the standard provided. 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: @@ -923,7 +920,6 @@ Syntactic Conventions This document uses the same syntactic conventions as the core X protocol encoding document. - A.1 Common Types ┌─── @@ -954,7 +950,7 @@ A.1 Common Types 0x3 Failed └─── Return status for requests which depend on time. - + ┌─── MODEINFO (40) Added in version 1.2 4 CARD32 id @@ -975,7 +971,7 @@ A.1 Common Types └─── An output mode specifies the complete CRTC timings for - a specfic mode. The vertical and horizontal synchronization rates + 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 @@ -1002,7 +998,6 @@ errors if used in version 1.0. 1 CARD32 major version 1 CARD32 minor version └─── - ┌─── RRSetScreenConfig @@ -1029,7 +1024,6 @@ errors if used in version 1.0. 4 CARD32 pad5 4 CARD32 pad6 └─── - ┌─── RRSelectInput @@ -1040,7 +1034,6 @@ errors if used in version 1.0. 2 SETofRRSELECTMASK enable 2 CARD16 pad └─── - ┌─── RRGetScreenInfo @@ -1096,7 +1089,6 @@ A.2.1 Protocol Requests added with version 1.2 4 unused 4 unused └─── - ┌─── RRSetScreenSize 1 CARD8 major opcode @@ -1108,7 +1100,6 @@ A.2.1 Protocol Requests added with version 1.2 4 CARD32 width in millimeters 4 CARD32 height in millimeters └─── - ┌─── RRGetScreenResources 1 CARD8 major opcode @@ -1133,7 +1124,6 @@ A.2.1 Protocol Requests added with version 1.2 b STRING8 mode names p unused, p=pad(b) └─── - ┌─── RRGetOutputInfo 1 CARD8 major opcode @@ -1159,11 +1149,10 @@ A.2.1 Protocol Requests added with version 1.2 n STRING8 name p unused, p=pad(n) └─── - ┌─── RRCreateMode 1 CARD8 major opcode - 1 0x09 RandR opcode + 1 0x0a RandR opcode 2 12+(n+p)/4 length 4 WINDOW window 40 MODEINFO mode @@ -1180,14 +1169,14 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRDestroyMode 1 CARD8 major opcode - 1 0x09 RandR opcode + 1 0x0b RandR opcode 2 2 length 4 MODE mode └─── ┌─── RRAddOutputMode 1 CARD8 major opcode - 1 0x09 RandR opcode + 1 0x0c RandR opcode 2 3 length 4 OUTPUT output 4 MODE mode @@ -1195,7 +1184,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRDeleteOutputMode 1 CARD8 major opcode - 1 0x09 RandR opcode + 1 0x0d RandR opcode 2 3 length 4 OUTPUT output 4 MODE mode @@ -1203,7 +1192,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetCrtcInfo 1 CARD8 major opcode - 1 RandR opcode + 1 0x0e RandR opcode 2 3 length 4 CRTC crtc 4 TIMESTAMP config-timestamp @@ -1228,7 +1217,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRSetCrtcConfig 1 CARD8 major opcode - 1 RandR opcode + 1 0x0f RandR opcode 2 7+n length 4 CRTC crtc 4 TIMESTAMP timestamp @@ -1288,7 +1277,7 @@ A.3.1 Protocol Events added with version 1.2 ┌─── RRCrtcChangeNotify 1 Base + 2 code - 1 0 sub-code + 1 1 sub-code 2 CARD16 sequence number 4 TIMESTAMP timestamp 4 WINDOW request window -- cgit v1.2.1 From b34676e8f709c4f8f6a2112c83103dfd0cabcbd7 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Wed, 13 Sep 2006 12:23:08 -0700 Subject: Add Output properties and CRTC Gamma ramps. Move sub-pixel to Output. The property requests mirror the core window property requests, except that notify events are delivered to windows, rather than to outputs. Gamma ramps lifted from XFree86V-idModeExtension; clients get to deal with converting single value to ramp though. Subpixel moved to output; clients get to figure out the effect of rotation on subpixel ordering. --- randrproto.txt | 327 +++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 304 insertions(+), 23 deletions(-) diff --git a/randrproto.txt b/randrproto.txt index a252f36..a87c011 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -207,7 +207,8 @@ ROTATION { Rotate_0 RRSELECTMASK { RRScreenChangeNotifyMask RRCrtcChangeNotifyMask (New in version 1.2) - RROutputChangeNotifyMask (New in version 1.2) } + RROutputChangeNotifyMask (New in version 1.2) + RROutputPropertyNotifyMask (New in version 1.2) } SIZEID { CARD16 } @@ -306,6 +307,10 @@ The name of this extension is "RANDR". 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 @@ -503,6 +508,7 @@ dynamic changes in the display environment. name: STRING connection: CONNECTION + subpixel-order: SUBPIXELORDER crtcs: LISTofCRTC clones: LISTofOUTPUT modes: LISTofMODE @@ -530,6 +536,9 @@ dynamic changes in the display environment. 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. + '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. @@ -543,6 +552,109 @@ dynamic changes in the display environment. connect this output to a CRTC not using one of these modes results in a Match error. +┌─── + RRListOutputProperties + output:OUTPUT + ▶ + atoms: LISTof ATOM +└─── + Errors: Output + + This request returns the atoms of properties currently defined on + the output. + +┌─── + 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 property for the specified output. 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 + ▶ + 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) + + 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 @@ -662,7 +774,6 @@ dynamic changes in the display environment. ▶ status: RRCONFIGSTATUS new-timestamp: TIMESTAMP - subpixelOrder: SUBPIXELORDER └─── Errors: Value, Match @@ -718,8 +829,42 @@ dynamic changes in the display environment. 'new-time-stamp' contains the time at which this request was executed. - 'subpixelOrder' contains the resulting subpixel order of the monitor - to allow correct subpixel rendering. +┌─── + 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. ❧❧❧❧❧❧❧❧❧❧❧ @@ -778,7 +923,6 @@ factors, such as re-cabling a monitor, etc. ┌─── RROutputChangeNotify: - sequence-number: CARD16 low 16 bits of request seq. number timestamp: TIMESTAMP time screen was reconfigured config-timestamp: TIMESTAMP time available config data was changed window: WINDOW window requesting notification @@ -798,8 +942,26 @@ factors, such as re-cabling a monitor, etc. system. ┌─── - RRCrtcChangeNotify /* XXX need to fit to 32 bytes */ - sequence-number: CARD16 low 16 bits of request seq. number + 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 @@ -807,7 +969,6 @@ factors, such as re-cabling a monitor, etc. crtc: CRTC CRTC which changed mode: MODE new mode rotation: ROTATION; new rotation - subpixelOrder: SUBPIXELORDER order of subpixels x: INT16 x position of CRTC within screen y: INT16 y position of CRTC within screen └─── @@ -843,9 +1004,9 @@ 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.0 of the specification, the +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 before 1.0 implemented: +list of what each version provided: 0.0: This prototype implemented resize and rotation in the TinyX server Used approximately the protocol described in @@ -870,7 +1031,9 @@ 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. +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. ❧❧❧❧❧❧❧❧❧❧❧ @@ -892,11 +1055,9 @@ defined by the extension. Version 2.0 of this extension added the ability to adjust the DAC values in a TrueColor server to modify the brightness curves of the display. -Most of the utility of this extension is subsumed by RandR version 1.2, -except for the gamma adjustments. If this features continue to be useful, -either some relationship between the screen indices used in the -XFree86-VidModeExtension and the screen/monitor pairs used int RandR or an -incorporation of this functionality into RandR might be needed. +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 @@ -976,6 +1137,7 @@ A.1 Common Types 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. A.2 Protocol Requests @@ -1084,10 +1246,7 @@ A.2.1 Protocol Requests added with version 1.2 2 CARD16 minHeight 2 CARD16 maxWidth 2 CARD16 maxHeight - 4 unused - 4 unused - 4 unused - 4 unused + 16 unused └─── ┌─── RRSetScreenSize @@ -1139,7 +1298,7 @@ A.2.1 Protocol Requests added with version 1.2 4 TIMESTAMP timestamp 4 CRTC current connected crtc 1 CONNECTION connection - 1 unused + 1 SUBPIXELORDER subpixel-order 2 c number of CRTCs 2 m number of modes 2 n length of name @@ -1149,6 +1308,85 @@ A.2.1 Protocol Requests added with version 1.2 n STRING8 name p unused, p=pad(n) └─── +┌─── + RRListOutputProperties + 1 CARD8 major opcode + 1 0x09 RandR opcode + 2 3 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 +└─── +┌─── + RRChangeOutputProperty + 1 CARD8 major opcode + 1 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 RandR opcode + 2 3 request length + 4 OUTPUT output + 4 ATOM property +└─── +┌─── + RRGetOutputProperty + 1 CARD8 major opcode + 1 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 + 3 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 @@ -1234,8 +1472,51 @@ A.2.1 Protocol Requests added with version 1.2 2 CARD16 sequence number 4 0 reply length 4 TIMESTAMP new timestamp - 2 SUBPIXELORDER subpixel order - 18 unused + 1 SUBPIXELORDER subpixel order + 19 unused +└─── +┌─── + RRGetCrtcGammaSize + 1 CARD8 major opcode + 1 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 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 0x0f 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 -- cgit v1.2.1 From 1cb8f4cda51fc256908a199c2599f46211c0cd52 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Wed, 13 Sep 2006 12:33:58 -0700 Subject: Fix RandR opcodes --- randrproto.txt | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/randrproto.txt b/randrproto.txt index a87c011..be6b5e2 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -1141,14 +1141,14 @@ A.1 Common Types A.2 Protocol Requests -Opcodes 0x1 and 0x3 were used in the 0.0 protocols, and will return +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 0x00 RandR opcode + 1 0 RandR opcode 2 3 length 4 CARD32 major version 4 CARD32 minor version @@ -1164,7 +1164,7 @@ errors if used in version 1.0. RRSetScreenConfig 1 CARD8 major opcode - 1 0x02 RandR opcode + 1 2 RandR opcode 2 6 length 4 WINDOW window on screen to be configured 4 TIMESTAMP timestamp @@ -1190,7 +1190,7 @@ errors if used in version 1.0. RRSelectInput 1 CARD8 major opcode - 1 0x04 RandR opcode + 1 4 RandR opcode 2 3 length 4 WINDOW window 2 SETofRRSELECTMASK enable @@ -1200,7 +1200,7 @@ errors if used in version 1.0. RRGetScreenInfo 1 CARD8 major opcode - 1 0x05 RandR opcode + 1 5 RandR opcode 2 2 length 4 WINDOW window ▶ @@ -1234,7 +1234,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetScreenSizeRange 1 CARD8 major opcode - 1 0x06 RandR opcode + 1 6 RandR opcode 2 2 length 4 WINDOW window ▶ @@ -1251,7 +1251,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRSetScreenSize 1 CARD8 major opcode - 1 0x07 RandR opcode + 1 7 RandR opcode 2 5 length 4 WINDOW window 2 CARD16 width @@ -1262,7 +1262,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetScreenResources 1 CARD8 major opcode - 1 0x08 RandR opcode + 1 8 RandR opcode 2 2 length 4 WINDOW window ▶ @@ -1286,7 +1286,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetOutputInfo 1 CARD8 major opcode - 1 0x09 RandR opcode + 1 9 RandR opcode 2 3 length 4 OUTPUT output 4 TIMESTAMP config-timestamp @@ -1311,7 +1311,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRListOutputProperties 1 CARD8 major opcode - 1 0x09 RandR opcode + 1 10 RandR opcode 2 3 length 4 OUTPUT output ▶ @@ -1326,7 +1326,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRChangeOutputProperty 1 CARD8 major opcode - 1 RandR opcode + 1 11 RandR opcode 2 6+(n+p)/4 request length 4 OUTPUT output 4 ATOM property @@ -1349,7 +1349,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRDeleteOutputProperty 1 CARD8 major opcode - 1 RandR opcode + 1 12 RandR opcode 2 3 request length 4 OUTPUT output 4 ATOM property @@ -1357,7 +1357,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetOutputProperty 1 CARD8 major opcode - 1 RandR opcode + 1 13 RandR opcode 2 7 request length 4 OUTPUT output 4 ATOM property @@ -1390,7 +1390,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRCreateMode 1 CARD8 major opcode - 1 0x0a RandR opcode + 1 14 RandR opcode 2 12+(n+p)/4 length 4 WINDOW window 40 MODEINFO mode @@ -1407,14 +1407,14 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRDestroyMode 1 CARD8 major opcode - 1 0x0b RandR opcode + 1 15 RandR opcode 2 2 length 4 MODE mode └─── ┌─── RRAddOutputMode 1 CARD8 major opcode - 1 0x0c RandR opcode + 1 16 RandR opcode 2 3 length 4 OUTPUT output 4 MODE mode @@ -1422,7 +1422,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRDeleteOutputMode 1 CARD8 major opcode - 1 0x0d RandR opcode + 1 17 RandR opcode 2 3 length 4 OUTPUT output 4 MODE mode @@ -1430,7 +1430,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetCrtcInfo 1 CARD8 major opcode - 1 0x0e RandR opcode + 1 18 RandR opcode 2 3 length 4 CRTC crtc 4 TIMESTAMP config-timestamp @@ -1455,7 +1455,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRSetCrtcConfig 1 CARD8 major opcode - 1 0x0f RandR opcode + 1 19 RandR opcode 2 7+n length 4 CRTC crtc 4 TIMESTAMP timestamp @@ -1478,7 +1478,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetCrtcGammaSize 1 CARD8 major opcode - 1 RandR opcode + 1 20 RandR opcode 2 2 length 4 CRTC crtc ▶ @@ -1492,7 +1492,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetCrtcGamma 1 CARD8 major opcode - 1 RandR opcode + 1 21 RandR opcode 2 2 length 4 CRTC crtc ▶ @@ -1509,7 +1509,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRSetCrtcGamma 1 CARD8 major opcode - 1 0x0f RandR opcode + 1 22 RandR opcode 2 3+(6n+2)/4 length 4 CRTC crtc 2 n size -- cgit v1.2.1 From 81ecda4300e007d62b36942fd6ac56a3ee1a1fa0 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Wed, 13 Sep 2006 12:35:05 -0700 Subject: Add .gitignore --- .gitignore | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c0562cd --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +*~ +Makefile +Makefile.in +aclocal.m4 +autom4te.cache +config.log +config.status +configure +install-sh +missing +randrproto.pc -- cgit v1.2.1 From e9a5a489acd591ff53823b406dca13c622439c14 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Thu, 14 Sep 2006 23:53:04 -0700 Subject: Update header files for new 1.2 spec. Fix missing bits in spec. Spec was missing a few things in the encoding section. --- randr.h | 35 +++-- randrproto.h | 437 ++++++++++++++++++++++++++++++++++++++++++++------------- randrproto.txt | 87 ++++++++---- 3 files changed, 426 insertions(+), 133 deletions(-) diff --git a/randr.h b/randr.h index 5975cdc..be00793 100644 --- a/randr.h +++ b/randr.h @@ -43,6 +43,7 @@ typedef unsigned short XRandrMonitor; #define RRNumberErrors 0 #define RRNumberEvents 2 +#define RRNumberRequests 12 #define X_RRQueryVersion 0 /* we skip 1 to make old clients fail pretty immediately */ @@ -56,24 +57,39 @@ typedef unsigned short XRandrMonitor; #define X_RRGetScreenInfo 5 /* V1.2 additions */ -#define X_RRGetScreenSizeRange 6 -#define X_RRSetScreenSize 7 -#define X_RRGetMonitorInfo 8 -#define X_RRAddMonitorMode 9 -#define X_RRDeleteMonitorMode 10 -#define X_RRSetMonitorConfig 11 +#define X_RRGetScreenSizeRange 6 +#define X_RRSetScreenSize 7 +#define X_RRGetScreenResources 8 +#define X_RRGetOutputInfo 9 +#define X_RRListOutputProperties 10 +#define X_RRChangeOutputProperty 11 +#define X_RRDeleteOutputProperty 12 +#define X_RRGetOutputProperty 13 +#define X_RRCreateMode 14 +#define X_RRDestroyMode 15 +#define X_RRAddOutputMode 16 +#define X_RRDeleteOutputMode 17 +#define X_RRGetCrtcInfo 18 +#define X_RRSetCrtcConfig 19 +#define X_RRGetCrtcGammaSize 20 +#define X_RRGetCrtcGamma 21 +#define X_RRSetCrtcGamma 22 /* Event selection bits */ #define RRScreenChangeNotifyMask (1L << 0) /* V1.2 additions */ -#define RRMonitorChangeNotifyMask (1L << 1) +#define RRCrtcChangeNotifyMask (1L << 1) +#define RROutputChangeNotifyMask (1L << 2) +#define RROutputPropertyNotifyMask (1L << 3) /* Event codes */ #define RRScreenChangeNotify 0 /* V1.2 additions */ -#define RRNotify 1 +#define RRNotify 1 /* RRNotify Subcodes */ -#define RRNotify_MonitorChange 0 +#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 @@ -92,7 +108,6 @@ typedef unsigned short XRandrMonitor; #define RRSetConfigFailed 3 /* new in 1.2 protocol */ -#define RR_MonitorDisabled 0xffff #define RR_HSyncPositive 0x00000001 #define RR_HSyncNegative 0x00000002 diff --git a/randrproto.h b/randrproto.h index 015df9a..9249239 100644 --- a/randrproto.h +++ b/randrproto.h @@ -43,11 +43,14 @@ #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 #define SubpixelOrder CARD16 -#define ModeID CARD16 /* * data structures @@ -175,17 +178,35 @@ typedef struct { * Additions for version 1.2 */ +typedef struct _xRRModeInfo { + RRMode id B32; + CARD16 width B16; + CARD16 height B16; + CARD32 mmWidth B32; + CARD32 mmHeight B32; + 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 B32; + RRModeFlags modeFlags B32; +} xRRModeInfo; + typedef struct { CARD8 reqType; CARD8 randrReqType; CARD16 length B16; - Window window B32; + Window window B32; } xRRGetScreenSizeRangeReq; #define sz_xRRGetScreenSizeRangeReq 8 typedef struct { BYTE type; /* X_Reply */ - CARD8 status; + CARD8 pad; CARD16 sequenceNumber B16; CARD32 length B32; CARD16 minWidth B16; @@ -216,108 +237,291 @@ typedef struct { CARD8 randrReqType; CARD16 length B16; Window window B32; -} xRRGetMonitorModesReq; - -typedef struct { - BYTE type; /* X_Reply */ - CARD8 status; - CARD16 sequenceNumber B16; - CARD32 length B32; - Window root B32; - CARD16 i B16; - CARD16 m B16; - CARD16 b B16; - CARD16 pad0 B16; - CARD32 pad1 B32; - CARD32 pad2 B32; - CARD32 pad3 B32; -} xRRGetMonitorModesReply; -#define sz_xRRGetMonitorModesReply 32 +} xRRGetScreenResourcesReq; +#define sz_xRRGetScreenResourcesReq 8 typedef struct { + BYTE type; + CARD8 pad; + CARD16 sequenceNumber B16; + CARD32 length B32; Time timestamp B32; Time configTimestamp B32; - INT16 x B16; - INT16 y B16; - Rotation rotation B16; - ModeID mode B16; - ModeID defaultMode B16; - Rotation rotations B16; - CARD16 firstMode B16; - CARD16 numModes B16; -} xRRMonitorInfo; -#define sz_xRRMonitorInfo 24 + CARD16 nCrtcs B16; + CARD16 nOutputs B16; + CARD16 nModes B16; + CARD16 nbytesNames B16; + CARD16 pad1 B16; + CARD32 pad2 B32; + CARD32 pad3 B32; +} xRRGetScreenResourcesReply; +#define sz_xRRGetScreenResourcesReply 32 typedef struct { - CARD16 width B16; - CARD16 height B16; - CARD32 widthInMillimeters B32; - CARD32 heightInMillimeters B32; - 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; - CARD32 modeFlags B32; -} xRRMonitorMode; -#define sz_xRRMonitorMode 36 + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RROutput output B32; + Time configTimestamp B32; +} xRRGetOutputInfoReq; +#define sz_xRRGetOutputInfoReq 12 typedef struct { - CARD8 reqType; - CARD8 randrReqType; - CARD16 length B16; - Window window B32; - CARD16 monitorIndex B16; - CARD16 pad B16; - xRRMonitorMode mode; -} xRRAddMonitorModeReq; -#define sz_xRRAddMonitorModeReq 48 + BYTE type; + CARD8 status; + CARD16 sequenceNumber B16; + CARD32 length B32; + Time timestamp B32; + RRCrtc crtc B32; + CARD8 connection; + CARD8 subpixelOrder; + CARD16 nCrtcs B16; + CARD16 nModes B16; + CARD16 nClones B16; + CARD16 nameLength B16; + CARD16 pad1 B16; + CARD32 pad2 B32; +} xRRGetOutputInfoReply; +#define sz_xRRGetOutputInfoReply 32 typedef struct { - CARD8 reqType; - CARD8 randrReqType; - CARD16 length B16; - Window window B32; - CARD16 monitorIndex B16; - CARD16 nameLength B16; -} xRRDeleteMonitorModeReq; -#define sz_xRRDeleteMonitorModeReq 12 + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RROutput output B32; +} xRRListOutputPropertiesReq; +#define sz_xRRListOutputPropertiesReq 8 typedef struct { - CARD8 reqType; + BYTE type; + CARD8 status; + 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; + 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; +} xDeleteOutputPropertyReq; +#define sz_xDeleteOutputPropertyReq 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; + CARD8 pad1; + CARD16 pad2; +} xGetOutputPropertyReq; +#define sz_xGetOutputPropertyReq 28 + +typedef struct { + BYTE type; + CARD8 status; + CARD16 sequenceNumber B16; + CARD32 length B32; + Atom propertyType B32; + CARD32 bytesAfter B32; + CARD32 nItems B32; + CARD32 pad1 B32; + CARD32 pad2 B32; + CARD32 pad3 B32; +} xGetOutputPropertyReply; +#define sz_xGetOutputPropertyReply 32 + +typedef struct { + CARD8 reqType; CARD8 randrReqType; CARD16 length B16; Window window B32; - Time timestamp B32; + xRRModeInfo modeInfo; +} xRRCreateModeReq; +#define sz_xRRCreateModeReq 48 + +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; - CARD16 monitorIndex B16; +} xGetCrtcInfoReq; +#define sz_xGetCrtcInfoReq 12 + +typedef struct { + BYTE type; + CARD8 status; + CARD16 sequenceNumber B16; + CARD32 length B32; INT16 x B16; INT16 y B16; - ModeID mode B16; + CARD16 width B16; + CARD16 height B16; + RRMode mode B32; Rotation rotation B16; - CARD16 pad B16; -} xRRSetMonitorConfigReq; -#define sz_xRRSetMonitorConfigReq 28 + Rotation rotations B16; + CARD16 nOutput B16; + CARD16 nPossibleOutput B16; + CARD32 pad1 B32; + CARD32 pad2 B32; +} xRRGetCrtcInfoReply; +#define sz_xRRGetCrtcInfoReply 32 typedef struct { - BYTE type; /* X_Reply */ - CARD8 status; - CARD16 sequenceNumber B16; - CARD32 length B32; - Time timestamp B32; - Time configTimestamp B32; - Window root B32; - SubpixelOrder subpixelOrder B16; - CARD16 monitor B16; - CARD32 pad1 B32; - CARD32 pad2 B32; -} xRRSetMonitorConfigReply; + 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 nOutputs B16; +} xRRSetCrtcConfigReq; +#define sz_xRRSetCrtcConfigReq 28 + +typedef struct { + BYTE type; + CARD8 status; + CARD16 sequenceNumber B16; + CARD32 length B32; + Time timestamp B32; + CARD8 subpixelOrder; + CARD8 pad1; + CARD16 pad2 B16; + CARD32 pad3 B32; + CARD32 pad4 B32; + CARD32 pad5 B32; + CARD32 pad6 B32; +} xRRSetCrtcConfigReply; +#define sz_xRRSetCrtcConfigReply 32 -#define sz_xRRSetMonitorConfigReply +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RRCrtc crtc B32; +} xGetCrtcGammaSizeReq; +#define sz_xGetCrtcGammaSizeReq 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; +} xGetCrtcGammaSizeReply; +#define sz_xGetCrtcGammaSizeReply 32 + +typedef struct { + CARD8 reqType; + CARD8 randrReqType; + CARD16 length B16; + RRCrtc crtc B32; +} xGetCrtcGammaReq; +#define sz_xGetCrtcGammaReq 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; +} xGetCrtcGammaReply; +#define sz_xGetCrtcGammaReply 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 @@ -326,8 +530,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 */ @@ -340,23 +544,58 @@ typedef struct { #define sz_xRRScreenChangeNotifyEvent 32 typedef struct { - CARD8 type; /* always evBase + RRNotify */ - CARD8 subCode; /* RRNotify_MonitorChange */ + CARD8 type; /* always evBase + RRNotify */ + CARD8 subCode; /* RRNotify_CrtcChange */ CARD16 sequenceNumber B16; - Time timestamp B32; /* time screen was changed */ - Time configTimestamp B32; /* time config data was changed */ - Window root B32; /* root window */ + Time timestamp B32; /* time crtc was changed */ Window window B32; /* window requesting notification */ - CARD16 monitor B16; /* monitor index */ - ModeID modeID B16; /* mode ID */ - Rotation rotation B16; /* rotation/reflection */ - SubpixelOrder subpixelOrder B16; /* new subpixel order */ - INT16 x B16; /* x */ - INT16 y B16; /* y */ -} xRRMonitorChangeNotifyEvent; -#define sz_xRRMonitorChangeNotifyEvent 32 + 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 -#undef Window +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 RROutput +#undef RRMode +#undef RRCrtc #undef Window #undef Font #undef Pixmap diff --git a/randrproto.txt b/randrproto.txt index be6b5e2..a0fc39d 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -230,15 +230,20 @@ SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render SCREENSIZE { widthInPixels, heightInPixels: CARD16 widthInMillimeters, heightInMillimeters: CARD16 } -MODEFLAG { hsync_positive hsync_negative - vsync_positive vsync_negative - interlace double_scan - csync csync_positive csync_negative - hskew_present - bcast - pixel_multiplex - double_clock - clock_divide_by_2 } +MODEFLAG { HSyncPositive + HSyncNegative + VSyncPositive + VSyncNegative + Interlace + DoubleScan + CSync + CSyncPositive + CSyncNegative + HSkewPresent + BCast + PixelMultiplex + DoubleClock + ClockDivideBy2 } MODEINFO { id: MODE name: STRING @@ -1100,6 +1105,7 @@ A.1 Common Types 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 @@ -1139,6 +1145,24 @@ A.1 Common Types 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 +└─── + A.2 Protocol Requests Opcodes 1 and 3 were used in the 0.0 protocols, and will return @@ -1301,8 +1325,9 @@ A.2.1 Protocol Requests added with version 1.2 1 SUBPIXELORDER subpixel-order 2 c number of CRTCs 2 m number of modes + 2 o number of clones 2 n length of name - 8 unused + 6 unused 4c LISTofCRTC crtcs 4m LISTofMODE modes n STRING8 name @@ -1541,11 +1566,27 @@ A.3 Protocol Events A.3.1 Protocol Events added with version 1.2 ┌─── - RROutputChangeNotify + 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 @@ -1556,20 +1597,18 @@ A.3.1 Protocol Events added with version 1.2 1 SUBPIXELORDER subpixel order └─── ┌─── - RRCrtcChangeNotify - 1 Base + 2 code - 1 1 sub-code + RROutputPropertyNotify + 1 Base + 1 code + 1 2 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 INT16 x - 2 INT16 y - 2 CARD16 width - 2 CARD16 height - 2 unused + 4 WINDOW window + 4 OUTPUT output + 4 ATOM atom + 4 TIMESTAMP time + 1 state + 0 NewValue + 1 Deleted + 11 unused └─── Bibliography -- cgit v1.2.1 From d6992dd3b7fcf22e4d670b29e8d0e2aba0d8e81d Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Fri, 15 Sep 2006 15:41:02 -0700 Subject: Add CONNECTION values to spec and header. Missing CONNECTION values in encoding and header file. --- randr.h | 4 ++++ randrproto.txt | 8 +++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/randr.h b/randr.h index be00793..94ae3a5 100644 --- a/randr.h +++ b/randr.h @@ -124,4 +124,8 @@ typedef unsigned short XRandrMonitor; #define RR_DoubleClock 0x00001000 #define RR_ClockDivideBy2 0x00002000 +#define RR_Connected 0 +#define RR_Disconnected 1 +#define RR_UnknownConnection 2 + #endif /* _RANDR_H_ */ diff --git a/randrproto.txt b/randrproto.txt index a0fc39d..cd9bfff 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -1162,7 +1162,13 @@ A.1 Common Types 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 -- cgit v1.2.1 From ce292d7cad17be4b13e4b7fad27b0ecbed101689 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sun, 17 Sep 2006 23:41:55 -0700 Subject: Fix various random typos found while attempting to use header files Fix RRNumberRequests Rename errors to include RR to avoid conflicting with Xi. Add RR to various request/reply structs (oops). Remove nOutputs from SetCrtcConfigReq -- length is sufficient. Remove bogus members from SetCrtcConfigReply. Add MODEOPTION. Document protocol error encoding. --- randr.h | 6 +++++- randrproto.h | 42 ++++++++++++++++++++---------------------- randrproto.txt | 22 ++++++++++++++++++---- 3 files changed, 43 insertions(+), 27 deletions(-) diff --git a/randr.h b/randr.h index 94ae3a5..6d9369f 100644 --- a/randr.h +++ b/randr.h @@ -43,7 +43,7 @@ typedef unsigned short XRandrMonitor; #define RRNumberErrors 0 #define RRNumberEvents 2 -#define RRNumberRequests 12 +#define RRNumberRequests 23 #define X_RRQueryVersion 0 /* we skip 1 to make old clients fail pretty immediately */ @@ -128,4 +128,8 @@ typedef unsigned short XRandrMonitor; #define RR_Disconnected 1 #define RR_UnknownConnection 2 +#define BadRROutput 0 +#define BadRRCrtc 1 +#define BadRRMode 2 + #endif /* _RANDR_H_ */ diff --git a/randrproto.h b/randrproto.h index 9249239..05327c4 100644 --- a/randrproto.h +++ b/randrproto.h @@ -327,8 +327,8 @@ typedef struct { CARD16 length B16; RROutput output B32; Atom property B32; -} xDeleteOutputPropertyReq; -#define sz_xDeleteOutputPropertyReq 12 +} xRRDeleteOutputPropertyReq; +#define sz_xRRDeleteOutputPropertyReq 12 typedef struct { CARD8 reqType; @@ -342,8 +342,8 @@ typedef struct { BOOL delete; CARD8 pad1; CARD16 pad2; -} xGetOutputPropertyReq; -#define sz_xGetOutputPropertyReq 28 +} xRRGetOutputPropertyReq; +#define sz_xRRGetOutputPropertyReq 28 typedef struct { BYTE type; @@ -356,8 +356,8 @@ typedef struct { CARD32 pad1 B32; CARD32 pad2 B32; CARD32 pad3 B32; -} xGetOutputPropertyReply; -#define sz_xGetOutputPropertyReply 32 +} xRRGetOutputPropertyReply; +#define sz_xRRGetOutputPropertyReply 32 typedef struct { CARD8 reqType; @@ -414,8 +414,8 @@ typedef struct { CARD16 length B16; RRCrtc crtc B32; Time configTimestamp B32; -} xGetCrtcInfoReq; -#define sz_xGetCrtcInfoReq 12 +} xRRGetCrtcInfoReq; +#define sz_xRRGetCrtcInfoReq 12 typedef struct { BYTE type; @@ -447,7 +447,7 @@ typedef struct { INT16 y B16; RRMode mode B32; Rotation rotation B16; - CARD16 nOutputs B16; + CARD16 pad B16; } xRRSetCrtcConfigReq; #define sz_xRRSetCrtcConfigReq 28 @@ -456,14 +456,12 @@ typedef struct { CARD8 status; CARD16 sequenceNumber B16; CARD32 length B32; - Time timestamp B32; - CARD8 subpixelOrder; - CARD8 pad1; - CARD16 pad2 B16; + Time newTimestamp B32; + CARD32 pad1 B32; + CARD32 pad2 B16; CARD32 pad3 B32; CARD32 pad4 B32; CARD32 pad5 B32; - CARD32 pad6 B32; } xRRSetCrtcConfigReply; #define sz_xRRSetCrtcConfigReply 32 @@ -472,8 +470,8 @@ typedef struct { CARD8 randrReqType; CARD16 length B16; RRCrtc crtc B32; -} xGetCrtcGammaSizeReq; -#define sz_xGetCrtcGammaSizeReq 8 +} xRRGetCrtcGammaSizeReq; +#define sz_xRRGetCrtcGammaSizeReq 8 typedef struct { BYTE type; @@ -487,16 +485,16 @@ typedef struct { CARD16 pad4 B32; CARD16 pad5 B32; CARD16 pad6 B32; -} xGetCrtcGammaSizeReply; -#define sz_xGetCrtcGammaSizeReply 32 +} xRRGetCrtcGammaSizeReply; +#define sz_xRRGetCrtcGammaSizeReply 32 typedef struct { CARD8 reqType; CARD8 randrReqType; CARD16 length B16; RRCrtc crtc B32; -} xGetCrtcGammaReq; -#define sz_xGetCrtcGammaReq 8 +} xRRGetCrtcGammaReq; +#define sz_xRRGetCrtcGammaReq 8 typedef struct { BYTE type; @@ -510,8 +508,8 @@ typedef struct { CARD16 pad4 B32; CARD16 pad5 B32; CARD16 pad6 B32; -} xGetCrtcGammaReply; -#define sz_xGetCrtcGammaReply 32 +} xRRGetCrtcGammaReply; +#define sz_xRRGetCrtcGammaReply 32 typedef struct { CARD8 reqType; diff --git a/randrproto.txt b/randrproto.txt index cd9bfff..c8d77a2 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -245,6 +245,10 @@ MODEFLAG { HSyncPositive DoubleClock ClockDivideBy2 } +MODEOPTION { ScalingNone, + ScalingMaxAspect, + ScalingMax } + MODEINFO { id: MODE name: STRING widthInPixels, heightInPixels: CARD16 @@ -252,7 +256,8 @@ MODEINFO { id: MODE dotClock: CARD32 hSyncStart, hSyncEnd, hTotal, hSkew: CARD16 vSyncStart, vSyncEnd, vTotal: CARD16 - modeFlags: SETofMODEFLAG } + modeFlags: SETofMODEFLAG + modeOptions: SETofMODEOPTION } REFRESH { rates: LISTofCARD16 } @@ -774,6 +779,7 @@ dynamic changes in the display environment. config-timestamp: TIMESTAMP x, y: INT16 mode: MODE + options: SETofMODEOPTION rotation: ROTATION outputs: LISTofOUTPUT ▶ @@ -1495,7 +1501,7 @@ A.2.1 Protocol Requests added with version 1.2 2 INT16 y 4 MODE mode 2 ROTATION rotation/reflection - 2 n number of outputs + 2 unused 4n LISTofOUTPUT outputs ▶ 1 1 Reply @@ -1503,8 +1509,7 @@ A.2.1 Protocol Requests added with version 1.2 2 CARD16 sequence number 4 0 reply length 4 TIMESTAMP new timestamp - 1 SUBPIXELORDER subpixel order - 19 unused + 20 unused └─── ┌─── RRGetCrtcGammaSize @@ -1617,6 +1622,15 @@ A.3.1 Protocol Events added with version 1.2 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 -- cgit v1.2.1 From 61d60a93dc0c827ef970f21f6b80099cc6c958f1 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Tue, 19 Sep 2006 16:33:40 -0700 Subject: Update package version to 1.2.0. Fix various goofs found by building stuff. --- configure.ac | 2 +- randr.h | 4 ++-- randrproto.h | 13 ++++++------- randrproto.txt | 4 ++-- 4 files changed, 11 insertions(+), 12 deletions(-) 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/randr.h b/randr.h index 6d9369f..43a616d 100644 --- a/randr.h +++ b/randr.h @@ -31,11 +31,11 @@ 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 short XRandrModeID; -typedef unsigned short XRandrMonitor; +typedef unsigned long XRandrModeFlags; #define RANDR_NAME "RANDR" #define RANDR_MAJOR 1 diff --git a/randrproto.h b/randrproto.h index 05327c4..cc78e6d 100644 --- a/randrproto.h +++ b/randrproto.h @@ -192,9 +192,10 @@ typedef struct _xRRModeInfo { CARD16 vSyncStart B16; CARD16 vSyncEnd B16; CARD16 vTotal B16; - CARD16 nameLength B32; + CARD16 nameLength B16; RRModeFlags modeFlags B32; } xRRModeInfo; +#define sz_xRRModeInfo 40 typedef struct { CARD8 reqType; @@ -251,9 +252,8 @@ typedef struct { CARD16 nOutputs B16; CARD16 nModes B16; CARD16 nbytesNames B16; - CARD16 pad1 B16; + CARD32 pad1 B32; CARD32 pad2 B32; - CARD32 pad3 B32; } xRRGetScreenResourcesReply; #define sz_xRRGetScreenResourcesReply 32 @@ -294,7 +294,7 @@ typedef struct { typedef struct { BYTE type; - CARD8 status; + CARD8 nProperties; CARD16 sequenceNumber B16; CARD32 length B32; CARD16 nAtoms B16; @@ -347,7 +347,7 @@ typedef struct { typedef struct { BYTE type; - CARD8 status; + CARD8 format; CARD16 sequenceNumber B16; CARD32 length B32; Atom propertyType B32; @@ -422,6 +422,7 @@ typedef struct { CARD8 status; CARD16 sequenceNumber B16; CARD32 length B32; + Time timestamp B32; INT16 x B16; INT16 y B16; CARD16 width B16; @@ -431,8 +432,6 @@ typedef struct { Rotation rotations B16; CARD16 nOutput B16; CARD16 nPossibleOutput B16; - CARD32 pad1 B32; - CARD32 pad2 B32; } xRRGetCrtcInfoReply; #define sz_xRRGetCrtcInfoReply 32 diff --git a/randrproto.txt b/randrproto.txt index c8d77a2..f0ec5e1 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -1312,7 +1312,7 @@ A.2.1 Protocol Requests added with version 1.2 2 o number of outputs 2 m number of modeinfos 2 b total bytes in mode names - 10 unused + 8 unused 4c LISTofCRTC crtcs 4o LISTofOUTPUT outputs 40m LISTofMODEINFO modeinfos @@ -1476,6 +1476,7 @@ A.2.1 Protocol Requests added with version 1.2 1 RRCONFIGSTATUS status 2 CARD16 sequence number 4 o+p reply length + 4 TIMESTATMP timestamp 2 INT16 x 2 INT16 y 2 CARD16 width @@ -1485,7 +1486,6 @@ A.2.1 Protocol Requests added with version 1.2 2 ROTATION set of possible rotations 2 o number of outputs 2 p number of possible outputs - 4 unused 4o LISTofOUTPUT outputs 4p LISTofOUTPUT possible outputs └─── -- cgit v1.2.1 From d6c9bdd0e6713a8c4dff53e88bd820ff1140758c Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Tue, 3 Oct 2006 11:01:56 -0700 Subject: Add mode origins and output options. Also document non-obvious defined types. Eliminate mode options. --- randrproto.txt | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 109 insertions(+), 9 deletions(-) diff --git a/randrproto.txt b/randrproto.txt index f0ec5e1..42c50d2 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -198,6 +198,30 @@ RRCONFIGSTATUS { Success 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 @@ -205,6 +229,10 @@ ROTATION { Rotate_0 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) @@ -214,12 +242,44 @@ SIZEID { CARD16 } MODE { XID or None } +RRMODEORIGIN { RRModeOriginPreferred, + RRModeOriginDetailed, + RRModeOriginVESA, + RRModeOriginConfig, + RRModeOriginUser, + RRModeOriginOther } + + These values are used to indicate to the application the origin + of each mode. + + Preferred modes come from the monitor as the preferred mode for + this monitor; generally these are used for fixed-pixel flat panels + to indicate the native resolution of the panel. + + Detailed modes also come from the monitor as additional modes that + may not follow the VESA specification. + + VESA modes are either standard modes from the VESA spec or modes + generated from the GTF using the monitor specifications. + + Config modes are those provided as a part of the X server + configuration. + + User modes are those defined through the RandR protocol during X + server operation. + + Other modes covers modes that come from any other source; space + aliens, tarot cards, whatever. + 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. @@ -245,10 +305,16 @@ MODEFLAG { HSyncPositive DoubleClock ClockDivideBy2 } -MODEOPTION { ScalingNone, - ScalingMaxAspect, - ScalingMax } +OUTPUTOPTION { RROutputOptionScaleNone, + RROutputOptionScaleMaxAspect, + RROutputOptionScaleMax } + These options select paramaters of the output which are independent + of the output mode. + + The scale options are used for fixed panels and select between + different scaling options for non-native resolutions. + MODEINFO { id: MODE name: STRING widthInPixels, heightInPixels: CARD16 @@ -257,7 +323,10 @@ MODEINFO { id: MODE hSyncStart, hSyncEnd, hTotal, hSkew: CARD16 vSyncStart, vSyncEnd, vTotal: CARD16 modeFlags: SETofMODEFLAG - modeOptions: SETofMODEOPTION } + modeOrigin: MODEORIGIN } + +OUTPUTCONFIG { output: OUTPUT + options: SETofOUTPUTOPTION } REFRESH { rates: LISTofCARD16 } @@ -515,10 +584,12 @@ dynamic changes in the display environment. status: RRCONFIGSTATUS timestamp: TIMESTAMP crtc: CRTC + options: SETofOUTPUTOPTION name: STRING connection: CONNECTION subpixel-order: SUBPIXELORDER + possible-options: SETofOUTPUTOPTION crtcs: LISTofCRTC clones: LISTofOUTPUT modes: LISTofMODE @@ -538,6 +609,8 @@ dynamic changes in the display environment. 'crtc' is the current source CRTC for video data, or Disabled if the output is not connected to any CRTC. + 'options' is the currently enabled set of options. + '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". @@ -549,6 +622,9 @@ dynamic changes in the display environment. 'subpixel-order' contains the resulting subpixel order of the connected device to allow correct subpixel rendering. + 'possible-options' indicate which options are supported by this + output device. + '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. @@ -779,7 +855,6 @@ dynamic changes in the display environment. config-timestamp: TIMESTAMP x, y: INT16 mode: MODE - options: SETofMODEOPTION rotation: ROTATION outputs: LISTofOUTPUT ▶ @@ -1124,6 +1199,17 @@ A.1 Common Types └─── Return status for requests which depend on time. +┌─── + RRMODEORIGIN + 0 RRModeOriginPreferred + 1 RRModeOriginDetailed + 2 RRModeOriginVESA + 3 RRModeOriginConfig + 4 RRModeOriginUser + 5 RRModeOriginOther +└─── + Origin of mode information. + ┌─── MODEINFO (40) Added in version 1.2 4 CARD32 id @@ -1174,6 +1260,18 @@ A.1 Common Types 1 Disconnected 2 UnknownConnection └─── +┌─── + OUTPUTOPTION + 1 RROutputOptionScaleNone + 2 RROutputOptionScaleMaxAspect + 4 RROutputOptionScaleMax +└─── +┌─── + OUTPUTCONFIG + 4 CARD32 output + 4 CARD32 set of output options +└─── + A.2 Protocol Requests @@ -1330,16 +1428,18 @@ A.2.1 Protocol Requests added with version 1.2 1 1 Reply 1 RRCONFIGSTATUS status 2 CARD16 sequence number - 4 c+m+(n+p)/4 reply length + 4 1+c+m+(n+p)/4 reply length 4 TIMESTAMP timestamp 4 CRTC current connected crtc + 4 SETofOUTPUTOPTION current output options 1 CONNECTION connection 1 SUBPIXELORDER subpixel-order 2 c number of CRTCs 2 m number of modes 2 o number of clones 2 n length of name - 6 unused + 2 unused + 4 SETofOUTPUTOPTION supported output options 4c LISTofCRTC crtcs 4m LISTofMODE modes n STRING8 name @@ -1493,7 +1593,7 @@ A.2.1 Protocol Requests added with version 1.2 RRSetCrtcConfig 1 CARD8 major opcode 1 19 RandR opcode - 2 7+n length + 2 7+2n length 4 CRTC crtc 4 TIMESTAMP timestamp 4 TIMESTAMP config timestamp @@ -1502,7 +1602,7 @@ A.2.1 Protocol Requests added with version 1.2 4 MODE mode 2 ROTATION rotation/reflection 2 unused - 4n LISTofOUTPUT outputs + 8n LISTofOUTPUTCONFIG outputs ▶ 1 1 Reply 1 RRCONFIGSTATUS status -- cgit v1.2.1 From ee843ac7077f5dcae677ad1b7c794abb0b89e111 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Tue, 3 Oct 2006 21:02:39 -0700 Subject: Add mode origins and output options. Mode origins indicate the source of the mode information, from VESA timings, user config or whatever. Output options currently include only panel fitting options; more may be added later (this field is 32 bits wide) --- randr.h | 11 +++++++++++ randrproto.h | 20 ++++++++++++++++---- randrproto.txt | 12 +++++++----- 3 files changed, 34 insertions(+), 9 deletions(-) diff --git a/randr.h b/randr.h index 43a616d..f0f81e1 100644 --- a/randr.h +++ b/randr.h @@ -132,4 +132,15 @@ typedef unsigned long XRandrModeFlags; #define BadRRCrtc 1 #define BadRRMode 2 +#define RRModeOriginPreferred 0 +#define RRModeOriginDetailed 1 +#define RRModeOriginVESA 2 +#define RRModeOriginConfig 3 +#define RRModeOriginUser 4 +#define RRModeOriginOther 5 + +#define RROutputOptionScaleNone 1 +#define RROutputOptionScaleMaxAspect 2 +#define RROutputOptionScaleMax 4 + #endif /* _RANDR_H_ */ diff --git a/randrproto.h b/randrproto.h index cc78e6d..d55e547 100644 --- a/randrproto.h +++ b/randrproto.h @@ -47,6 +47,8 @@ #define RRMode CARD32 #define RRCrtc CARD32 #define RRModeFlags CARD32 +#define RROutputOptions CARD32 +#define RRModeOrigin CARD8 #define Rotation CARD16 #define SizeID CARD16 @@ -194,8 +196,17 @@ typedef struct _xRRModeInfo { CARD16 vTotal B16; CARD16 nameLength B16; RRModeFlags modeFlags B32; + RRModeOrigin origin; + CARD8 pad1; + CARD16 pad2 B16; } xRRModeInfo; -#define sz_xRRModeInfo 40 +#define sz_xRRModeInfo 44 + +typedef struct { + RROutput output B32; + RROutputOptions options B32; +} xRROutputConfig; +#define sz_xRROutputConfig 8 typedef struct { CARD8 reqType; @@ -273,6 +284,7 @@ typedef struct { CARD32 length B32; Time timestamp B32; RRCrtc crtc B32; + RROutputOptions currentOptions B32; CARD8 connection; CARD8 subpixelOrder; CARD16 nCrtcs B16; @@ -280,9 +292,9 @@ typedef struct { CARD16 nClones B16; CARD16 nameLength B16; CARD16 pad1 B16; - CARD32 pad2 B32; + RROutputOptions possibleOptions B32; } xRRGetOutputInfoReply; -#define sz_xRRGetOutputInfoReply 32 +#define sz_xRRGetOutputInfoReply 36 typedef struct { CARD8 reqType; @@ -366,7 +378,7 @@ typedef struct { Window window B32; xRRModeInfo modeInfo; } xRRCreateModeReq; -#define sz_xRRCreateModeReq 48 +#define sz_xRRCreateModeReq 52 typedef struct { BYTE type; diff --git a/randrproto.txt b/randrproto.txt index 42c50d2..15ab34f 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -1211,7 +1211,7 @@ A.1 Common Types Origin of mode information. ┌─── - MODEINFO (40) Added in version 1.2 + MODEINFO (44) Added in version 1.2 4 CARD32 id 2 CARD16 width in pixels 2 CARD16 height in pixels @@ -1227,6 +1227,8 @@ A.1 Common Types 2 CARD16 v total 2 CARD16 name length 4 SETofMODEFLAG mode flags + 1 MODEORIGIN mode origin + 3 unused └─── An output mode specifies the complete CRTC timings for @@ -1403,7 +1405,7 @@ A.2.1 Protocol Requests added with version 1.2 1 1 Reply 1 unused 2 CARD16 sequence number - 4 c+o+10m+(b+p)/4 reply length + 4 c+o+11m+(b+p)/4 reply length 4 TIMESTAMP timestamp 4 TIMESTAMP config-timestamp 2 c number of CRTCs @@ -1413,7 +1415,7 @@ A.2.1 Protocol Requests added with version 1.2 8 unused 4c LISTofCRTC crtcs 4o LISTofOUTPUT outputs - 40m LISTofMODEINFO modeinfos + 44m LISTofMODEINFO modeinfos b STRING8 mode names p unused, p=pad(b) └─── @@ -1528,9 +1530,9 @@ A.2.1 Protocol Requests added with version 1.2 RRCreateMode 1 CARD8 major opcode 1 14 RandR opcode - 2 12+(n+p)/4 length + 2 13+(n+p)/4 length 4 WINDOW window - 40 MODEINFO mode + 44 MODEINFO mode n STRING8 mode name p unused, p=pad(n) ▶ -- cgit v1.2.1 From 3c354e7245dd7830b5600716185017831aff1316 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Wed, 4 Oct 2006 14:51:48 -0700 Subject: Get rid of mode origins. --- randr.h | 11 +++++------ randrproto.txt | 36 +++++++----------------------------- 2 files changed, 12 insertions(+), 35 deletions(-) diff --git a/randr.h b/randr.h index f0f81e1..202eb23 100644 --- a/randr.h +++ b/randr.h @@ -132,12 +132,11 @@ typedef unsigned long XRandrModeFlags; #define BadRRCrtc 1 #define BadRRMode 2 -#define RRModeOriginPreferred 0 -#define RRModeOriginDetailed 1 -#define RRModeOriginVESA 2 -#define RRModeOriginConfig 3 -#define RRModeOriginUser 4 -#define RRModeOriginOther 5 +#define RRModeOriginMonitor 0 +#define RRModeOriginVESA 1 +#define RRModeOriginConfig 2 +#define RRModeOriginUser 3 +#define RRModeOriginOther 4 #define RROutputOptionScaleNone 1 #define RROutputOptionScaleMaxAspect 2 diff --git a/randrproto.txt b/randrproto.txt index 15ab34f..6e64557 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -242,34 +242,12 @@ SIZEID { CARD16 } MODE { XID or None } -RRMODEORIGIN { RRModeOriginPreferred, - RRModeOriginDetailed, - RRModeOriginVESA, - RRModeOriginConfig, - RRModeOriginUser, - RRModeOriginOther } - - These values are used to indicate to the application the origin - of each mode. - - Preferred modes come from the monitor as the preferred mode for - this monitor; generally these are used for fixed-pixel flat panels - to indicate the native resolution of the panel. - - Detailed modes also come from the monitor as additional modes that - may not follow the VESA specification. - - VESA modes are either standard modes from the VESA spec or modes - generated from the GTF using the monitor specifications. - - Config modes are those provided as a part of the X server - configuration. - - User modes are those defined through the RandR protocol during X - server operation. - - Other modes covers modes that come from any other source; space - aliens, tarot cards, whatever. +OUTPUTPREFERENCE { RROutputPreferencePreferred, + RROutputPreferenceMonitor, + RROutputPreference + +OUTPUTMODE { mode: MODE, + preference: OUTPUTPREFERENCE } CRTC { XID } @@ -592,7 +570,7 @@ dynamic changes in the display environment. possible-options: SETofOUTPUTOPTION crtcs: LISTofCRTC clones: LISTofOUTPUT - modes: LISTofMODE + modes: LISTofOUTPUTMODE └─── Errors: Output -- cgit v1.2.1 From 369d4e7d2030c707cf2ce37d06c1d23b0570910c Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Wed, 4 Oct 2006 20:03:35 -0700 Subject: Remove mode origins. Add preferred mode count. Switched from identifying source of mode line to listing which modes are preferred by each output. This enables better CRTC sharing by making modes less arbitrarily different. --- randr.h | 7 +------ randrproto.h | 15 +++++++-------- randrproto.txt | 44 ++++++++++++++------------------------------ 3 files changed, 22 insertions(+), 44 deletions(-) diff --git a/randr.h b/randr.h index 202eb23..77ec5e4 100644 --- a/randr.h +++ b/randr.h @@ -36,6 +36,7 @@ typedef unsigned short XRandrRotation; typedef unsigned short XRandrSizeID; typedef unsigned short XRandrSubpixelOrder; typedef unsigned long XRandrModeFlags; +typedef unsigned long XRandrOutputOptions; #define RANDR_NAME "RANDR" #define RANDR_MAJOR 1 @@ -132,12 +133,6 @@ typedef unsigned long XRandrModeFlags; #define BadRRCrtc 1 #define BadRRMode 2 -#define RRModeOriginMonitor 0 -#define RRModeOriginVESA 1 -#define RRModeOriginConfig 2 -#define RRModeOriginUser 3 -#define RRModeOriginOther 4 - #define RROutputOptionScaleNone 1 #define RROutputOptionScaleMaxAspect 2 #define RROutputOptionScaleMax 4 diff --git a/randrproto.h b/randrproto.h index d55e547..90549bd 100644 --- a/randrproto.h +++ b/randrproto.h @@ -48,7 +48,6 @@ #define RRCrtc CARD32 #define RRModeFlags CARD32 #define RROutputOptions CARD32 -#define RRModeOrigin CARD8 #define Rotation CARD16 #define SizeID CARD16 @@ -196,11 +195,8 @@ typedef struct _xRRModeInfo { CARD16 vTotal B16; CARD16 nameLength B16; RRModeFlags modeFlags B32; - RRModeOrigin origin; - CARD8 pad1; - CARD16 pad2 B16; } xRRModeInfo; -#define sz_xRRModeInfo 44 +#define sz_xRRModeInfo 40 typedef struct { RROutput output B32; @@ -289,9 +285,9 @@ typedef struct { CARD8 subpixelOrder; CARD16 nCrtcs B16; CARD16 nModes B16; + CARD16 nPreferred B16; CARD16 nClones B16; CARD16 nameLength B16; - CARD16 pad1 B16; RROutputOptions possibleOptions B32; } xRRGetOutputInfoReply; #define sz_xRRGetOutputInfoReply 36 @@ -378,7 +374,7 @@ typedef struct { Window window B32; xRRModeInfo modeInfo; } xRRCreateModeReq; -#define sz_xRRCreateModeReq 52 +#define sz_xRRCreateModeReq 48 typedef struct { BYTE type; @@ -601,7 +597,10 @@ typedef struct { } xRROutputPropertyNotifyEvent; #define sz_xRROUtputPropertyNotifyEvent 32 - +#undef RROutputOptions +#undef RRModeFlags +#undef RRCrtc +#undef RRMode #undef RROutput #undef RRMode #undef RRCrtc diff --git a/randrproto.txt b/randrproto.txt index 6e64557..01b284c 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -242,13 +242,6 @@ SIZEID { CARD16 } MODE { XID or None } -OUTPUTPREFERENCE { RROutputPreferencePreferred, - RROutputPreferenceMonitor, - RROutputPreference - -OUTPUTMODE { mode: MODE, - preference: OUTPUTPREFERENCE } - CRTC { XID } OUTPUT { XID } @@ -300,8 +293,7 @@ MODEINFO { id: MODE dotClock: CARD32 hSyncStart, hSyncEnd, hTotal, hSkew: CARD16 vSyncStart, vSyncEnd, vTotal: CARD16 - modeFlags: SETofMODEFLAG - modeOrigin: MODEORIGIN } + modeFlags: SETofMODEFLAG } OUTPUTCONFIG { output: OUTPUT options: SETofOUTPUTOPTION } @@ -570,7 +562,8 @@ dynamic changes in the display environment. possible-options: SETofOUTPUTOPTION crtcs: LISTofCRTC clones: LISTofOUTPUT - modes: LISTofOUTPUTMODE + modes: LISTofOUTPUT + num-preferred: CARD16 └─── Errors: Output @@ -616,6 +609,10 @@ dynamic changes in the display environment. 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 @@ -1178,18 +1175,7 @@ A.1 Common Types Return status for requests which depend on time. ┌─── - RRMODEORIGIN - 0 RRModeOriginPreferred - 1 RRModeOriginDetailed - 2 RRModeOriginVESA - 3 RRModeOriginConfig - 4 RRModeOriginUser - 5 RRModeOriginOther -└─── - Origin of mode information. - -┌─── - MODEINFO (44) Added in version 1.2 + MODEINFO (40) Added in version 1.2 4 CARD32 id 2 CARD16 width in pixels 2 CARD16 height in pixels @@ -1205,8 +1191,6 @@ A.1 Common Types 2 CARD16 v total 2 CARD16 name length 4 SETofMODEFLAG mode flags - 1 MODEORIGIN mode origin - 3 unused └─── An output mode specifies the complete CRTC timings for @@ -1249,7 +1233,7 @@ A.1 Common Types ┌─── OUTPUTCONFIG 4 CARD32 output - 4 CARD32 set of output options + 4 OUTPUTOPTION set of output options └─── @@ -1383,7 +1367,7 @@ A.2.1 Protocol Requests added with version 1.2 1 1 Reply 1 unused 2 CARD16 sequence number - 4 c+o+11m+(b+p)/4 reply length + 4 c+o+10m+(b+p)/4 reply length 4 TIMESTAMP timestamp 4 TIMESTAMP config-timestamp 2 c number of CRTCs @@ -1393,7 +1377,7 @@ A.2.1 Protocol Requests added with version 1.2 8 unused 4c LISTofCRTC crtcs 4o LISTofOUTPUT outputs - 44m LISTofMODEINFO modeinfos + 40m LISTofMODEINFO modeinfos b STRING8 mode names p unused, p=pad(b) └─── @@ -1416,9 +1400,9 @@ A.2.1 Protocol Requests added with version 1.2 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 - 2 unused 4 SETofOUTPUTOPTION supported output options 4c LISTofCRTC crtcs 4m LISTofMODE modes @@ -1508,9 +1492,9 @@ A.2.1 Protocol Requests added with version 1.2 RRCreateMode 1 CARD8 major opcode 1 14 RandR opcode - 2 13+(n+p)/4 length + 2 12+(n+p)/4 length 4 WINDOW window - 44 MODEINFO mode + 40 MODEINFO mode n STRING8 mode name p unused, p=pad(n) ▶ -- cgit v1.2.1 From 0e858436af67256c0af49317183df4bf8092183c Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Wed, 1 Nov 2006 00:23:37 -0800 Subject: Move physical size information from mode to output. Modes are stored in CRTCs which have no physical size. Outputs have a physical size which can change, both in response to mode changes as well as (potentially) other factors. Placing the physical size information in the output also permits clone mode to work across monitors of differing physical size. --- randrproto.h | 10 +++++----- randrproto.txt | 12 +++++++++--- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/randrproto.h b/randrproto.h index 90549bd..cff3061 100644 --- a/randrproto.h +++ b/randrproto.h @@ -183,8 +183,6 @@ typedef struct _xRRModeInfo { RRMode id B32; CARD16 width B16; CARD16 height B16; - CARD32 mmWidth B32; - CARD32 mmHeight B32; CARD32 dotClock B32; CARD16 hSyncStart B16; CARD16 hSyncEnd B16; @@ -196,7 +194,7 @@ typedef struct _xRRModeInfo { CARD16 nameLength B16; RRModeFlags modeFlags B32; } xRRModeInfo; -#define sz_xRRModeInfo 40 +#define sz_xRRModeInfo 32 typedef struct { RROutput output B32; @@ -281,6 +279,8 @@ typedef struct { Time timestamp B32; RRCrtc crtc B32; RROutputOptions currentOptions B32; + CARD32 mmWidth B32; + CARD32 mmHeight B32; CARD8 connection; CARD8 subpixelOrder; CARD16 nCrtcs B16; @@ -290,7 +290,7 @@ typedef struct { CARD16 nameLength B16; RROutputOptions possibleOptions B32; } xRRGetOutputInfoReply; -#define sz_xRRGetOutputInfoReply 36 +#define sz_xRRGetOutputInfoReply 44 typedef struct { CARD8 reqType; @@ -374,7 +374,7 @@ typedef struct { Window window B32; xRRModeInfo modeInfo; } xRRCreateModeReq; -#define sz_xRRCreateModeReq 48 +#define sz_xRRCreateModeReq 40 typedef struct { BYTE type; diff --git a/randrproto.txt b/randrproto.txt index 01b284c..20543bf 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -288,8 +288,7 @@ OUTPUTOPTION { RROutputOptionScaleNone, MODEINFO { id: MODE name: STRING - widthInPixels, heightInPixels: CARD16 - widthInMillimeters, heightInMillimeters: CARD32 + width, height: CARD16 dotClock: CARD32 hSyncStart, hSyncEnd, hTotal, hSkew: CARD16 vSyncStart, vSyncEnd, vTotal: CARD16 @@ -559,6 +558,7 @@ dynamic changes in the display environment. name: STRING connection: CONNECTION subpixel-order: SUBPIXELORDER + widthInMillimeters, heightInMillimeters: CARD32 possible-options: SETofOUTPUTOPTION crtcs: LISTofCRTC clones: LISTofOUTPUT @@ -593,6 +593,10 @@ dynamic changes in the display environment. '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. + 'possible-options' indicate which options are supported by this output device. @@ -1392,10 +1396,12 @@ A.2.1 Protocol Requests added with version 1.2 1 1 Reply 1 RRCONFIGSTATUS status 2 CARD16 sequence number - 4 1+c+m+(n+p)/4 reply length + 4 3+c+m+(n+p)/4 reply length 4 TIMESTAMP timestamp 4 CRTC current connected crtc 4 SETofOUTPUTOPTION current output options + 4 CARD32 width in millimeters + 4 CARD32 height in millimeters 1 CONNECTION connection 1 SUBPIXELORDER subpixel-order 2 c number of CRTCs -- cgit v1.2.1 From 96977842d01220bd4a294375c669b26ff30275d1 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Wed, 1 Nov 2006 11:50:50 -0800 Subject: Fix RRNumberErrors, start adding standard property names --- randr.h | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/randr.h b/randr.h index 77ec5e4..7d3e123 100644 --- a/randr.h +++ b/randr.h @@ -42,7 +42,7 @@ typedef unsigned long XRandrOutputOptions; #define RANDR_MAJOR 1 #define RANDR_MINOR 2 -#define RRNumberErrors 0 +#define RRNumberErrors 3 #define RRNumberEvents 2 #define RRNumberRequests 23 @@ -137,4 +137,8 @@ typedef unsigned long XRandrOutputOptions; #define RROutputOptionScaleMaxAspect 2 #define RROutputOptionScaleMax 4 +/* Conventional RandR output properties */ + +#define RR_PROPERTY_RANDR_EDID "RANDR_EDID" + #endif /* _RANDR_H_ */ -- cgit v1.2.1 From cdc282c2995dc17dee97c6da24a9705478cf792e Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Thu, 16 Nov 2006 08:50:49 -0800 Subject: Remove output options. Clean up other sizes. Output options will be controlled by properties instead. Also found a few instances in randrproto.txt using the wrong size for MODEINFO. --- randr.h | 5 ----- randrproto.h | 12 +----------- randrproto.txt | 47 ++++++----------------------------------------- 3 files changed, 7 insertions(+), 57 deletions(-) diff --git a/randr.h b/randr.h index 7d3e123..935db85 100644 --- a/randr.h +++ b/randr.h @@ -36,7 +36,6 @@ typedef unsigned short XRandrRotation; typedef unsigned short XRandrSizeID; typedef unsigned short XRandrSubpixelOrder; typedef unsigned long XRandrModeFlags; -typedef unsigned long XRandrOutputOptions; #define RANDR_NAME "RANDR" #define RANDR_MAJOR 1 @@ -133,10 +132,6 @@ typedef unsigned long XRandrOutputOptions; #define BadRRCrtc 1 #define BadRRMode 2 -#define RROutputOptionScaleNone 1 -#define RROutputOptionScaleMaxAspect 2 -#define RROutputOptionScaleMax 4 - /* Conventional RandR output properties */ #define RR_PROPERTY_RANDR_EDID "RANDR_EDID" diff --git a/randrproto.h b/randrproto.h index cff3061..314b9ae 100644 --- a/randrproto.h +++ b/randrproto.h @@ -47,7 +47,6 @@ #define RRMode CARD32 #define RRCrtc CARD32 #define RRModeFlags CARD32 -#define RROutputOptions CARD32 #define Rotation CARD16 #define SizeID CARD16 @@ -196,12 +195,6 @@ typedef struct _xRRModeInfo { } xRRModeInfo; #define sz_xRRModeInfo 32 -typedef struct { - RROutput output B32; - RROutputOptions options B32; -} xRROutputConfig; -#define sz_xRROutputConfig 8 - typedef struct { CARD8 reqType; CARD8 randrReqType; @@ -278,7 +271,6 @@ typedef struct { CARD32 length B32; Time timestamp B32; RRCrtc crtc B32; - RROutputOptions currentOptions B32; CARD32 mmWidth B32; CARD32 mmHeight B32; CARD8 connection; @@ -288,9 +280,8 @@ typedef struct { CARD16 nPreferred B16; CARD16 nClones B16; CARD16 nameLength B16; - RROutputOptions possibleOptions B32; } xRRGetOutputInfoReply; -#define sz_xRRGetOutputInfoReply 44 +#define sz_xRRGetOutputInfoReply 36 typedef struct { CARD8 reqType; @@ -597,7 +588,6 @@ typedef struct { } xRROutputPropertyNotifyEvent; #define sz_xRROUtputPropertyNotifyEvent 32 -#undef RROutputOptions #undef RRModeFlags #undef RRCrtc #undef RRMode diff --git a/randrproto.txt b/randrproto.txt index 20543bf..dccee75 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -276,16 +276,6 @@ MODEFLAG { HSyncPositive DoubleClock ClockDivideBy2 } -OUTPUTOPTION { RROutputOptionScaleNone, - RROutputOptionScaleMaxAspect, - RROutputOptionScaleMax } - - These options select paramaters of the output which are independent - of the output mode. - - The scale options are used for fixed panels and select between - different scaling options for non-native resolutions. - MODEINFO { id: MODE name: STRING width, height: CARD16 @@ -294,9 +284,6 @@ MODEINFO { id: MODE vSyncStart, vSyncEnd, vTotal: CARD16 modeFlags: SETofMODEFLAG } -OUTPUTCONFIG { output: OUTPUT - options: SETofOUTPUTOPTION } - REFRESH { rates: LISTofCARD16 } ❧❧❧❧❧❧❧❧❧❧❧ @@ -553,13 +540,11 @@ dynamic changes in the display environment. status: RRCONFIGSTATUS timestamp: TIMESTAMP crtc: CRTC - options: SETofOUTPUTOPTION name: STRING connection: CONNECTION subpixel-order: SUBPIXELORDER widthInMillimeters, heightInMillimeters: CARD32 - possible-options: SETofOUTPUTOPTION crtcs: LISTofCRTC clones: LISTofOUTPUT modes: LISTofOUTPUT @@ -580,8 +565,6 @@ dynamic changes in the display environment. 'crtc' is the current source CRTC for video data, or Disabled if the output is not connected to any CRTC. - 'options' is the currently enabled set of options. - '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". @@ -597,9 +580,6 @@ dynamic changes in the display environment. size of the displayed area. If unknown, or not really fixed (e.g., for a projector), these values are both zero. - 'possible-options' indicate which options are supported by this - output device. - '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. @@ -1179,12 +1159,10 @@ A.1 Common Types Return status for requests which depend on time. ┌─── - MODEINFO (40) Added in version 1.2 + MODEINFO (32) Added in version 1.2 4 CARD32 id 2 CARD16 width in pixels 2 CARD16 height in pixels - 4 CARD32 width in millimeters - 4 CARD32 height in millimeters 4 CARD32 dot clock 2 CARD16 h sync start 2 CARD16 h sync end @@ -1228,17 +1206,6 @@ A.1 Common Types 1 Disconnected 2 UnknownConnection └─── -┌─── - OUTPUTOPTION - 1 RROutputOptionScaleNone - 2 RROutputOptionScaleMaxAspect - 4 RROutputOptionScaleMax -└─── -┌─── - OUTPUTCONFIG - 4 CARD32 output - 4 OUTPUTOPTION set of output options -└─── A.2 Protocol Requests @@ -1371,7 +1338,7 @@ A.2.1 Protocol Requests added with version 1.2 1 1 Reply 1 unused 2 CARD16 sequence number - 4 c+o+10m+(b+p)/4 reply length + 4 c+o+8m+(b+p)/4 reply length 4 TIMESTAMP timestamp 4 TIMESTAMP config-timestamp 2 c number of CRTCs @@ -1381,7 +1348,7 @@ A.2.1 Protocol Requests added with version 1.2 8 unused 4c LISTofCRTC crtcs 4o LISTofOUTPUT outputs - 40m LISTofMODEINFO modeinfos + 32m LISTofMODEINFO modeinfos b STRING8 mode names p unused, p=pad(b) └─── @@ -1396,10 +1363,9 @@ A.2.1 Protocol Requests added with version 1.2 1 1 Reply 1 RRCONFIGSTATUS status 2 CARD16 sequence number - 4 3+c+m+(n+p)/4 reply length + 4 1+c+m+(n+p)/4 reply length 4 TIMESTAMP timestamp 4 CRTC current connected crtc - 4 SETofOUTPUTOPTION current output options 4 CARD32 width in millimeters 4 CARD32 height in millimeters 1 CONNECTION connection @@ -1409,7 +1375,6 @@ A.2.1 Protocol Requests added with version 1.2 2 p number of preferred modes 2 o number of clones 2 n length of name - 4 SETofOUTPUTOPTION supported output options 4c LISTofCRTC crtcs 4m LISTofMODE modes n STRING8 name @@ -1500,7 +1465,7 @@ A.2.1 Protocol Requests added with version 1.2 1 14 RandR opcode 2 12+(n+p)/4 length 4 WINDOW window - 40 MODEINFO mode + 32 MODEINFO mode n STRING8 mode name p unused, p=pad(n) ▶ @@ -1572,7 +1537,7 @@ A.2.1 Protocol Requests added with version 1.2 4 MODE mode 2 ROTATION rotation/reflection 2 unused - 8n LISTofOUTPUTCONFIG outputs + 8n LISTofOUTPUT outputs ▶ 1 1 Reply 1 RRCONFIGSTATUS status -- cgit v1.2.1 From af852261efa5eb7f8d16e3e90b8832bf66d93de7 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Mon, 20 Nov 2006 20:58:16 -0800 Subject: Change properties to have a pending value and report valid values. Pending values are transferred to current values at mode set, allowing a queue of values to accrue in preparation for the modeset operation while still reporting valid 'current' values for applications. The set of valid values is also available so applications can present a reasonable list to the user during configuration. I renumbered a bunch of requests to keep property requests sequential. --- randr.h | 28 ++++++------ randrproto.h | 42 +++++++++++++++++- randrproto.txt | 132 +++++++++++++++++++++++++++++++++++++++++++++++---------- 3 files changed, 165 insertions(+), 37 deletions(-) diff --git a/randr.h b/randr.h index 935db85..17e6ef9 100644 --- a/randr.h +++ b/randr.h @@ -43,7 +43,7 @@ typedef unsigned long XRandrModeFlags; #define RRNumberErrors 3 #define RRNumberEvents 2 -#define RRNumberRequests 23 +#define RRNumberRequests 25 #define X_RRQueryVersion 0 /* we skip 1 to make old clients fail pretty immediately */ @@ -62,18 +62,20 @@ typedef unsigned long XRandrModeFlags; #define X_RRGetScreenResources 8 #define X_RRGetOutputInfo 9 #define X_RRListOutputProperties 10 -#define X_RRChangeOutputProperty 11 -#define X_RRDeleteOutputProperty 12 -#define X_RRGetOutputProperty 13 -#define X_RRCreateMode 14 -#define X_RRDestroyMode 15 -#define X_RRAddOutputMode 16 -#define X_RRDeleteOutputMode 17 -#define X_RRGetCrtcInfo 18 -#define X_RRSetCrtcConfig 19 -#define X_RRGetCrtcGammaSize 20 -#define X_RRGetCrtcGamma 21 -#define X_RRSetCrtcGamma 22 +#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) diff --git a/randrproto.h b/randrproto.h index 314b9ae..aa9d35f 100644 --- a/randrproto.h +++ b/randrproto.h @@ -306,6 +306,44 @@ typedef struct { } 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; + CARD8 nProperties; + CARD16 sequenceNumber B16; + CARD32 length B32; + BOOL pending; + BOOL range; + BOOL immutable; + BOOL pad0; + 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; @@ -339,8 +377,8 @@ typedef struct { CARD32 longOffset B32; CARD32 longLength B32; BOOL delete; - CARD8 pad1; - CARD16 pad2; + BOOL pending; + CARD16 pad1 B16; } xRRGetOutputPropertyReq; #define sz_xRRGetOutputPropertyReq 28 diff --git a/randrproto.txt b/randrproto.txt index dccee75..c9d0144 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -121,7 +121,7 @@ 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 Tippet and Kevin Martin for splitting outputs and CRTCs to more +Matthew Tippett and Kevin Martin for splitting outputs and CRTCs to more fully expose what video hardware can do ❧❧❧❧❧❧❧❧❧❧❧ @@ -608,6 +608,56 @@ dynamic changes in the display environment. 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 does not exist for the specified output, + then a Name error is returned. + + 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. + ┌─── RRChangeOutputProperty output: OUTPUT @@ -618,10 +668,14 @@ dynamic changes in the display environment. └─── Errors: Alloc, Atom, Match, Value, Output - This request alters the property for the specified output. 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. + 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 @@ -659,6 +713,7 @@ dynamic changes in the display environment. type: ATOM or AnyPropertyType long-offset, long-length: CARD32 delete: BOOL + pending: BOOL ▶ type: ATOM or None format: {0, 8, 16, 32} @@ -692,9 +747,11 @@ dynamic changes in the display environment. L = MINIMUM(T, 4 × long-length) A = N - (I + L) - 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 + If 'pending' is true, 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 @@ -1384,7 +1441,7 @@ A.2.1 Protocol Requests added with version 1.2 RRListOutputProperties 1 CARD8 major opcode 1 10 RandR opcode - 2 3 length + 2 2 length 4 OUTPUT output ▶ 1 1 Reply @@ -1396,9 +1453,39 @@ A.2.1 Protocol Requests added with version 1.2 4n LISTofATOM atoms └─── ┌─── - RRChangeOutputProperty + 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 @@ -1421,7 +1508,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRDeleteOutputProperty 1 CARD8 major opcode - 1 12 RandR opcode + 1 14 RandR opcode 2 3 request length 4 OUTPUT output 4 ATOM property @@ -1429,7 +1516,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetOutputProperty 1 CARD8 major opcode - 1 13 RandR opcode + 1 15 RandR opcode 2 7 request length 4 OUTPUT output 4 ATOM property @@ -1438,7 +1525,8 @@ A.2.1 Protocol Requests added with version 1.2 4 CARD32 long-offset 4 CARD32 long-length 1 BOOL delete - 3 unused + 1 BOOL pending + 2 unused ▶ 1 1 Reply 1 CARD8 format @@ -1462,7 +1550,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRCreateMode 1 CARD8 major opcode - 1 14 RandR opcode + 1 16 RandR opcode 2 12+(n+p)/4 length 4 WINDOW window 32 MODEINFO mode @@ -1479,14 +1567,14 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRDestroyMode 1 CARD8 major opcode - 1 15 RandR opcode + 1 17 RandR opcode 2 2 length 4 MODE mode └─── ┌─── RRAddOutputMode 1 CARD8 major opcode - 1 16 RandR opcode + 1 18 RandR opcode 2 3 length 4 OUTPUT output 4 MODE mode @@ -1494,7 +1582,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRDeleteOutputMode 1 CARD8 major opcode - 1 17 RandR opcode + 1 19 RandR opcode 2 3 length 4 OUTPUT output 4 MODE mode @@ -1502,7 +1590,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetCrtcInfo 1 CARD8 major opcode - 1 18 RandR opcode + 1 20 RandR opcode 2 3 length 4 CRTC crtc 4 TIMESTAMP config-timestamp @@ -1527,7 +1615,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRSetCrtcConfig 1 CARD8 major opcode - 1 19 RandR opcode + 1 21 RandR opcode 2 7+2n length 4 CRTC crtc 4 TIMESTAMP timestamp @@ -1549,7 +1637,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetCrtcGammaSize 1 CARD8 major opcode - 1 20 RandR opcode + 1 22 RandR opcode 2 2 length 4 CRTC crtc ▶ @@ -1563,7 +1651,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRGetCrtcGamma 1 CARD8 major opcode - 1 21 RandR opcode + 1 23 RandR opcode 2 2 length 4 CRTC crtc ▶ @@ -1580,7 +1668,7 @@ A.2.1 Protocol Requests added with version 1.2 ┌─── RRSetCrtcGamma 1 CARD8 major opcode - 1 22 RandR opcode + 1 24 RandR opcode 2 3+(6n+2)/4 length 4 CRTC crtc 2 n size -- cgit v1.2.1 From a86f4b9442a48a3049e03a4c7d4fd022a860bf01 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Fri, 24 Nov 2006 13:44:55 -0800 Subject: Create Properties when configured. Pending defaults to Current Change property semantics to create them with empty value when they are configured. When clients request the Pending value of a property without any pending vlaue, the current value is returned instead. --- randrproto.txt | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/randrproto.txt b/randrproto.txt index c9d0144..bde1fdf 100644 --- a/randrproto.txt +++ b/randrproto.txt @@ -649,15 +649,15 @@ dynamic changes in the display environment. └─── Errors: Access, Name, Atom, Output - If the specified property does not exist for the specified output, - then a Name error is returned. - 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 @@ -747,15 +747,15 @@ dynamic changes in the display environment. L = MINIMUM(T, 4 × long-length) A = N - (I + L) - If 'pending' is true, 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. + 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 -- cgit v1.2.1 From 7363d448c77c2d2ec2928d9d4bc41aac1c2d36b7 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Fri, 24 Nov 2006 13:45:25 -0800 Subject: Use BYTE for one-byte values. #undef Drawable needed. --- randrproto.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/randrproto.h b/randrproto.h index aa9d35f..fe40c0e 100644 --- a/randrproto.h +++ b/randrproto.h @@ -317,13 +317,13 @@ typedef struct { typedef struct { BYTE type; - CARD8 nProperties; + BYTE pad0; CARD16 sequenceNumber B16; CARD32 length B32; BOOL pending; BOOL range; BOOL immutable; - BOOL pad0; + BYTE pad1; CARD16 pad2 B16; CARD32 pad3 B32; CARD32 pad4 B32; @@ -632,6 +632,7 @@ typedef struct { #undef RROutput #undef RRMode #undef RRCrtc +#undef Drawable #undef Window #undef Font #undef Pixmap -- cgit v1.2.1