	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.
