520 lines
17 KiB
Plaintext
520 lines
17 KiB
Plaintext
The X Resize, Rotate and Reflect Extension
|
|
Version 1.0
|
|
2002-10-4
|
|
|
|
Jim Gettys
|
|
Jim.Gettys@hp.com
|
|
|
|
Keith Packard
|
|
keithp@xfree86.org
|
|
|
|
Cambridge Research Laboratory
|
|
HP Labs
|
|
Hewlett Packard Company
|
|
|
|
1. Introduction
|
|
|
|
The X Resize, Rotate and Reflect Extension, called RandR for short,
|
|
brings the ability to resize, rotate and reflect the root window of a
|
|
screen. It is based on the X Resize and Rotate Extension as specified
|
|
in the Proceedings of the 2001 Usenix Technical Conference [RANDR].
|
|
|
|
RandR as implemented and integrated into the XFree86 server differs in
|
|
one substantial fashion from the design discussed in that paper: that
|
|
is, RandR 1.0 does not implement the depth switching described in that
|
|
document, and the support described for that in the protocol in that
|
|
document and in the XFree86 implementationhas been removed from the
|
|
protocol described here, as it has been overtaken by events.
|
|
|
|
These events include:
|
|
o Modern toolkits (in this case, GTK+ 2.x) have progressed to the point
|
|
of implementing migration between screens of arbitrary depths
|
|
o The continued advance of Moore's law has made limited amounts of VRAM
|
|
less of an issue, reducing the pressure to implement depth switching
|
|
on laptops or desktop systems
|
|
o The continued decline of legacy toolkits whose design would have
|
|
required depth switching to support migration
|
|
o The lack of depth switchin implementation experience in the
|
|
intervening time, due to events beyond our control
|
|
|
|
Additionally, the requirement to support depth switching might
|
|
complicate other re-engineering of the device independent part of the
|
|
X server that is currently being contemplated.
|
|
|
|
Rather than further delaying RandR's widespread deployment for a
|
|
feature long wanted by the community (resizing of screens,
|
|
particularly on laptops), or the deployment of a protocol design that
|
|
might be flawed due to lack of implementation experience, we decided
|
|
to remove depth switching from the protocol. It may be implementated
|
|
at a later time if resources and interests permit as a revision to the
|
|
protocol described here, which will remain a stable base for
|
|
applications. The protocol described here has been implemented in the
|
|
main XFree86 server, and more fully in the TinyX implementation in the
|
|
XFree86 distribution, which fully implements resizing, rotation and
|
|
reflection.
|
|
|
|
2. Acknowlegements
|
|
|
|
Our thanks to the contributors to the design found on the xpert mailing list.
|
|
|
|
2. Screen change model
|
|
|
|
Screens may change dynamically, either under control of this
|
|
extension, or due to external events. Examples include: monitors being
|
|
swapped, you pressing a button to switch from internal display to an
|
|
external monitor on a laptop, or, eventually, the hotplug of a display
|
|
card entirely on busses such as Cardbus which permit hot-swap (which
|
|
will require other work in addition to this extension).
|
|
|
|
Since the screen configuration is dynamic and asynchronous to the
|
|
client and may change at any time RandR provides mechanisms to ensure
|
|
that your clients view is up to date with the configuration
|
|
possibilities of the moment and enforces applications that wish to
|
|
control the configuration to prove that their information is up to
|
|
date before honoring requests to change the screen configuration (by
|
|
requiring a timestamp on the request).
|
|
|
|
Interested applications are notified whenever the screen configuration
|
|
changes, providing the current size of the screen and subpixel order
|
|
(see the Render extension [RENDER]), to enabel proper rendering of
|
|
subpixel decimated client text to continue, along with a time stamp of
|
|
the configuration change. A client must refresh its knowledge of the
|
|
screen configuration before attempting to change the configuration
|
|
after a notification, or the request will fail.
|
|
|
|
To avoid multiplicative explosion between orientation, reflection
|
|
and sizes, the sizes are only those sizes in the normal (0) rotation.
|
|
|
|
Rotation and reflection and how they interact can be confusing. In
|
|
Randr, the coordinate system is rotated in a counter-clockwise
|
|
direction relative to the normal orientation. Reflection is along the
|
|
window system coordinate system, not the physical screen X and Y axis,
|
|
so that rotation and reflection do not interact. The other way to
|
|
consider reflection is to is specified in the "normal" orientation,
|
|
before rotation, if you find the other way confusing.
|
|
|
|
We expect that most clients and toolkits will be oblivious to changes
|
|
to the screen stucture, as they generally use the values in the
|
|
connections Display structure directly. By toolkits updating the
|
|
values on the fly, we believe pop-up menus and other pop up windows
|
|
will position themselves correctly in the face of screen configuration
|
|
changes (the issue is ensuring that pop-ups are visible on the
|
|
reconfigured screen).
|
|
|
|
3. Data Types
|
|
|
|
The subpixel order is shared with the Render extension, and is
|
|
documented there. The only datatype defined is the screen size,
|
|
defined in the normal (0 degree) orientation.
|
|
|
|
|
|
4. Errors
|
|
|
|
There are no new error types defined by this extension.
|
|
|
|
5. Protocol Types
|
|
|
|
ROTATION {
|
|
RR_rotate_0
|
|
RR_rotate_90
|
|
RR_rotate_180
|
|
RR_rotate_270
|
|
RR-Reflect_X
|
|
RR_Reflect_Y }
|
|
|
|
RRSELECTMASK { RRScreenChangeNotifyMask }
|
|
|
|
SIZEID { CARD16 }
|
|
|
|
SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render
|
|
SubPixelHorizontalRGB extensions definitions; they are here
|
|
SubPixelHorizontalBGR only for convenience.
|
|
SubPixelVerticalRGB
|
|
SubPixelVerticalBGR
|
|
SubPixelNone }
|
|
|
|
|
|
6. Extension Initialization
|
|
|
|
The name of this extension is "RANDR".
|
|
|
|
RRQueryVersion
|
|
client-major-version: CARD32
|
|
client-minor-version: CARD32
|
|
->
|
|
major-version: CARD32
|
|
minor-version: CARD32
|
|
|
|
The client sends the highest supported version to the server
|
|
and the server sends the highest version it supports, but no
|
|
higher than the requested version. Major versions changes can
|
|
introduce incompatibilities in existing functionality, minor
|
|
version changes introduce only backward compatible changes.
|
|
It is the clients responsibility to ensure that the server
|
|
supports a version which is compatible with its expectations.
|
|
|
|
7. Extension Requests
|
|
|
|
RRSelectInput
|
|
window: WINDOW
|
|
enable: SETofRRSELECTMASK
|
|
|
|
Errors: BadWindow, BadValue
|
|
|
|
If enable is RRScreenChangeNotifyMask, RRScreenChangeNotify
|
|
events will be sent anytime the screen configuration changes,
|
|
either from this protocol extension, or due to detected
|
|
external screen configuration changes. RRScreenChangeNotify
|
|
may also be sent immediately if the screen configuration has
|
|
changed since the client connected, to avoid race conditions.
|
|
|
|
RRSetScreenConfig
|
|
drawable: DRAWABLE
|
|
timestamp: TIMESTAMP
|
|
config-timestamp: TIMESTAMP
|
|
sizeID: SIZEID
|
|
rotation: ROTATION
|
|
rate: CARD16
|
|
|
|
->
|
|
|
|
new-timestamp: TIMESTAMP
|
|
config-timestamp: TIMESTAMP
|
|
root: WINDOW
|
|
subpixelOrder: SUBPIXELORDER
|
|
|
|
Errors: BadValue, BadMatch
|
|
|
|
If the timestamp in this request is less than the time when
|
|
the configuration was last successfully set, the request is
|
|
ignored and False returned in success. If the
|
|
config-timestamp in this request is not equal to when the
|
|
server's screen configurations last changed, the request is
|
|
ignored and False returned in success. This could occur if
|
|
the screen changed since you last made a RRGetScreenInfo
|
|
request, perhaps by a different piece of display hardware
|
|
being installed. Rather than allowing an incorrect call to be
|
|
executed based on stale data, the server will ignore the
|
|
request.
|
|
|
|
If rate is zero, the server selects an appropriate rate.
|
|
|
|
If the request succeeds, this request sets the screen to the
|
|
specified size, rate, rotation and reflection. If the requests
|
|
succeeds, the new-time-stamp is returned containing the time
|
|
when the screen configuration was changed and config-timestamp
|
|
is returned to indicate when the possible screen
|
|
configurations were last changed, and success is set to True.
|
|
The root window for the screen indicated by the drawable
|
|
argument is also returned, along with the subpixel order, to
|
|
allow correct subpixel rendering.
|
|
|
|
BadValue errors are generated if the rotation is not an
|
|
allowed rotation. BadValue errors are generated, if, when the
|
|
timestamps would allow the operation to succeed, or size-index
|
|
are not possible (out of range).
|
|
|
|
|
|
RRGetScreenInfo
|
|
window: WINDOW
|
|
|
|
->
|
|
|
|
rotations: SETofROTATION
|
|
root: WINDOW
|
|
timestamp: TIMESTAMP
|
|
config-timestamp: TIMESTAMP
|
|
nSizes: CARD16
|
|
sizeID: SIZEID
|
|
rotation: ROTATION
|
|
rate: CARD16
|
|
sizes: LISTofSCREENSIZE
|
|
refresh: LISTofREFRESH
|
|
|
|
where:
|
|
|
|
SCREENSIZE {
|
|
widthInPixels, heightInPixels: CARD16
|
|
widthInMillimeters, heightInMillimeters: CARD16 }
|
|
|
|
REFRESH {
|
|
rates: LISTofCARD16
|
|
}
|
|
|
|
Errors: BadWindow
|
|
|
|
This event is delivered to clients selecting for notification
|
|
with RRSelectInput requests using a RRScreenChangeNotifyMask.
|
|
|
|
Size-index indicates which size is active. The returned
|
|
window is the window requsting notification.
|
|
|
|
This call returns the root window of the screen which has changed.
|
|
|
|
Rotations contains the set of rotations and reflections
|
|
supported by the screen of the window requested. The root
|
|
window of that screen is reported. The number of current sizes
|
|
supported is returned, along with which size rotation and
|
|
reflection the screen is currently set to.
|
|
|
|
The config-timestamp indicates when the screen configuration
|
|
information last changed: requests to set the screen will fail
|
|
unless the timestamp indicates that the information the client
|
|
is using is up to date, to ensure clients can be well behaved
|
|
in the face of race conditions. Similarly, timestamp indicates
|
|
when the configuration was last set, and must both must be up
|
|
to date in a call to RRSetScreenConfig for it to succeed.
|
|
|
|
Rate is the current refresh rate. This is zero when the refresh
|
|
rate is unknown or on devices for which refresh is not relevant.
|
|
|
|
Sizes is the list of possible frame buffer sizes (at the
|
|
normal orientation, each provide both the linear physical size
|
|
of the screen and the pixel size.
|
|
|
|
Refresh is the list of refresh rates for each size, each element
|
|
of sizes has a cooresponding element in refresh. An empty list
|
|
indicates no known rates, or a device for which refresh is not
|
|
relevant.
|
|
|
|
The default size of the screen (the size that would become the
|
|
current size when the server resets) is the first size in the
|
|
list. The potential screen sizes themselves are also
|
|
returned.
|
|
|
|
Toolkits SHOULD use RRScreenChangeSelectInput to be notified
|
|
via a RRScreenChangeNotify event, so that they can adapt to
|
|
screen size changes.
|
|
|
|
|
|
8. Extension Events
|
|
|
|
Clients MAY select for ConfigureNotify on the root window to be
|
|
informed of screen changes. This may be advantageous if all your
|
|
clients need to know is the size of the root window, as it avoids
|
|
round trips to set up the extension.
|
|
|
|
RRScreenChangeNotify is sent if RRSelectInput has requested it
|
|
whenever properties of the screen change, which may be due to external
|
|
factors, such as recabling a monitor, etc.
|
|
|
|
RRScreenChangeNotify
|
|
|
|
rotation: ROTATION; new rotation
|
|
sequenceNumber: CARD16 low 16 bits of request's seq. number
|
|
timestamp: TIMESTAMP time screen was changed
|
|
configTimestamp: TIMESTAMP time config data was changed
|
|
root: WINDOW root window of screen
|
|
window: WINDOW window requesting notification
|
|
sizeID: SIZEID new ID of size
|
|
subpixelOrder: SUBPIXELORDER order of subpixels
|
|
widthInPixels: INT16
|
|
heightInPixels: INT16
|
|
widthInMillimeters: INT16
|
|
heightInMillimeters: INT16
|
|
|
|
This event is generated whenever the screen configuration is
|
|
changed and sent to requesting clients. The timestamp included
|
|
indicates when the screen configuration was changed, and
|
|
configTimestamp says when the last time the configuration was
|
|
changed. The root is the root of the screen the change
|
|
occurred on, and the event window is also returned. SizeID
|
|
contains an index indicating which size is current.
|
|
|
|
This event is sent whenever the screen's configuration changes
|
|
or if a new screen configuration becomes available that was
|
|
not available in the past. In this case (config-timestamp in
|
|
the event not being equal to the config-timestamp returned in
|
|
the last call to RRGetScreenInfo), the client MUST call
|
|
RRGetScreenInfo to update its view of possible screen
|
|
configurations to have a correct view of possible screen
|
|
organizations. Timestamp is set to when the active screen
|
|
configuration was changed.
|
|
|
|
Clients which select screen change notification events may be
|
|
sent an event immediately if the screen configuration was
|
|
changed between when they connected to the X server and
|
|
selected for notification. This is to prevent a common race
|
|
that might occur on log-in, where many applications start up
|
|
just at the time when a display manager or log in script might
|
|
be changing the screen size or configuration.
|
|
|
|
|
|
9. Extension Versioning
|
|
|
|
The RandR extension was developed in parallel with the implementation
|
|
to ensure the feasibility of various portions of the design. As
|
|
portions of the extension are implemented, the version number of the
|
|
extension has changed to reflect the portions of the standard provied.
|
|
This document describes the version 1.0 of the specification, the
|
|
partial implementations have version numbers less than that. Here's a
|
|
list of what each version before 1.0 implemented:
|
|
|
|
0.0: This prototype implemented resize and rotation in the
|
|
TinyX server Used approximately the protocol described in
|
|
the Usenix paper. Appeared in the TinyX server in
|
|
XFree86 4.2, but not in the XFree86 main server.
|
|
|
|
0.1: Added subpixel order, added an event for subpixel order.
|
|
This version was never checked in to XFree86 CVS.
|
|
|
|
1.0: Implements resize, rotation, and reflection. Implemented
|
|
both in the XFree86 main server (size change only at this
|
|
date), and fully (size change, rotation, and reflection)
|
|
in XFree86's TinyX server.
|
|
|
|
1.1: Added refresh rates
|
|
|
|
Compatibility between 0.0 and 1.0 was *NOT* preserved, and 0.0 clients
|
|
will fail against 1.0 servers. The wire encoding op-codes were
|
|
changed for GetScreenInfo to ensure this failure in a relatively
|
|
graceful way. Version 1.1 servers and clients are cross compatible with
|
|
1.0. Version 1.1 is considered to be stable and we intend upward
|
|
compatibility from this point.
|
|
|
|
|
|
Appendix A. Protocol Encoding
|
|
|
|
Syntactic Conventions
|
|
|
|
This document uses the same syntactic conventions as the core X
|
|
protocol encoding document.
|
|
|
|
|
|
A.1 Common Types
|
|
|
|
SETofROTATION
|
|
|
|
0x0001 RR_Rotate_0
|
|
0x0002 RR_Rotate_90
|
|
0x0004 RR_Rotate_180
|
|
0x0008 RR_Rotate_270
|
|
0x0010 RR_Reflect_X
|
|
0x0020 RR_Reflect_Y
|
|
|
|
|
|
SETofRRSELECTMASK
|
|
|
|
0x0001 RRScreenChangeNotifyMask
|
|
|
|
|
|
A.2 Protocol Requests
|
|
|
|
|
|
Opcodes 0x1 and 0x3 were used in the 0.0 protocols, and will return
|
|
errors if used in version 1.0.
|
|
|
|
RRQueryVersion
|
|
|
|
1 CARD8 major opcode
|
|
1 0x01 RandR opcode
|
|
2 3 length
|
|
4 CARD32 major version
|
|
4 CARD32 minor version
|
|
->
|
|
1 1 Reply
|
|
1 unused
|
|
2 CARD16 sequence number
|
|
4 0 reply length
|
|
1 CARD32 major version
|
|
1 CARD32 minor version
|
|
|
|
RRSetScreenConfig
|
|
|
|
1 CARD8 major opcode
|
|
1 0x02 RandR opcode
|
|
2 5 length
|
|
4 DRAWABLE drawable on screen to be configured
|
|
4 TIMESTAMP timestamp
|
|
2 SIZEID size id
|
|
2 ROTATION rotation/reflection
|
|
2 CARD16 refresh rate (1.1 only)
|
|
2 CARD16 pad
|
|
->
|
|
1 1 Reply
|
|
1 CARD8 status
|
|
0x0 RRSetConfigSuccess
|
|
0x1 RRSetConfigInvalidConfigTime
|
|
0x2 RRSetConfigInvalidTime
|
|
0x3 RRSetConfigFailed
|
|
2 CARD16 sequence number
|
|
4 0 reply length
|
|
4 TIMESTAMP new timestamp
|
|
4 TIMESTAMP new configuration timestamp
|
|
4 WINDOW root
|
|
2 SUBPIXELORDER subpixel order defined in Render
|
|
2 CARD16 pad4
|
|
4 CARD32 pad5
|
|
4 CARD32 pad6
|
|
|
|
|
|
RRSelectInput
|
|
|
|
1 CARD8 major opcode
|
|
1 0x04 RandR opcode
|
|
2 3 length
|
|
4 WINDOW window
|
|
2 SETofRRSELECTMASK enable
|
|
2 CARD16 pad
|
|
|
|
|
|
RRGetScreenInfo
|
|
|
|
1 CARD8 major opcode
|
|
1 0x05 RandR opcode
|
|
2 2 length
|
|
4 WINDOW window
|
|
->
|
|
1 1 Reply
|
|
1 CARD8 set of Rotations
|
|
2 CARD16 sequence number
|
|
4 0 reply length
|
|
4 WINDOW root window
|
|
4 TIMESTAMP timestamp
|
|
4 TIMESTAMP config timestamp
|
|
2 CARD16 number of SIZE following
|
|
2 SIZEID sizeID
|
|
2 ROTATION current rotation and reflection
|
|
2 CARD16 rate (1.1)
|
|
2 CARD16 length of rate info (number of CARD16s)
|
|
2 CARD16 pad
|
|
|
|
SIZE
|
|
2 CARD16 width in pixels
|
|
2 CARD16 height in pixels
|
|
2 CARD16 width in millimeters
|
|
2 CARD16 height in millimeters
|
|
|
|
REFRESH
|
|
2 CARD16 number of rates (n)
|
|
2n CARD16 rates
|
|
|
|
A.2 Protocol Event
|
|
|
|
RRScreenChangeNotify
|
|
|
|
1 Base + 0 code
|
|
1 ROTATION new rotation and reflection
|
|
2 CARD16 sequence number
|
|
4 TIMESTAMP timestamp
|
|
4 TIMESTAMP configuration timestamp
|
|
4 WINDOW root window
|
|
4 WINDOW request window
|
|
2 SIZEID size ID
|
|
2 SUBPIXELORDER subpixel order defined in Render
|
|
2 CARD16 width in pixels
|
|
2 CARD16 height in pixels
|
|
2 CARD16 width in millimeters
|
|
2 CARD16 height in millimeters
|
|
|
|
|
|
Bibliography
|
|
|
|
[RANDR] Gettys, Jim and Keith Packard, "The X Resize and Rotate
|
|
Extension - RandR", Proceedings of the 2001 USENIX Annual
|
|
Technical Conference, Boston, MA
|
|
|
|
[RENDER]
|
|
Packard, Keith, "The X Rendering Extension", work in progress,
|
|
documents found in xc/specs/Render.
|