Xrandr is a simple library designed to interface the X Resize and Rotate Extension. This allows clients to change the size and rotation of the root window of a screen, along with the ability to reflect the screen about either axis (if supported by the implementation). Rotation and reflection may be implemented by software and may result in slower performance if rotation and reflection are implemented in this fashion (as are all implementations as of October 2002).
The Xrandr library does some minimal caching to avoid roundtrips to provide clients frequently used information. See "The X Resize and Rotate Extension" for a detailed description; also note that depth switching, as described in the document is not implemented, and may (or may not) ever be implemented, as display memory is growing rapidly, and toolkits are already beginning to support migration, mitigating the need for depth switching. If it is implemented in the future, we expect to do so via an upward compatible extension to the current library/protocol; functionality described here should continue to work.
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.
The XRRScreenChangeNotify event is sent to clients that ask to be informed whenever the root window configuration changes. Configuration changes may include resolution, physical size, subpixel order (see XRender(3)), and rotation. Note that changes to any or all of these could occur due to external events (user control in the X server, a different monitor/flat panel display being hot-plugged) and is not only the result of a protocol/library request to the X server.
Additionally, to eliminate a potential race condition, this event may be generated immediately upon selecting for notification if the screen has changed since the client of Xrandr connected to the X server, to enable reliable screen resolution changing when a user may log in and change the configuration while one or many clients are starting up.
Xlib notification
Clients must call back into Xlib using XRRUpdateConfiguration when screen configuration change notify events are generated (or root window configuration changes occur, to update Xlib's view of the resolution, size, rotation, reflection or subpixel order. Generally, toolkits will perform this operation on behalf of applications; we did not want to change display structure data behind the back of toolkits, as in multithreaded clients, various race conditions might occur. Toolkits should provide clients some mechanism for notification of screen change, of course.