1XRANDR(3) Library Functions Manual XRANDR(3)
2
6 Xrandr - X Resize, Rotate and Reflection extension.
7
9 #include <X11/extensions/Xrandr.h>
10 Bool XRRQueryExtension (Display *dpy,
12 int *event_base_return, int *error_base_return);
13 Status XRRQueryVersion (Display *dpy,
15 int *major_version_return,
16 int *minor_version_return);
17 XRRScreenConfiguration *XRRGetScreenInfo (Display *dpy,
19 Drawable draw);
20 void XRRFreeScreenConfigInfo (
22 XRRScreenConfiguration *config);
23 Status XRRSetScreenConfig (Display *dpy,
25 XRRScreenConfiguration *config,
26 Drawable draw,
27 int size_index,
28 Rotation rotation,
29 Time timestamp);
30 Status XRRSetScreenConfigAndRate (Display *dpy,
32 XRRScreenConfiguration *config,
33 Drawable draw,
34 int size_index,
35 Rotation rotation,
36 short rate,
37 Time timestamp);
38 Rotation XRRConfigRotations(
40 XRRScreenConfiguration *config,
41 Rotation *current_rotation);
42 Time XRRConfigTimes (
44 XRRScreenConfiguration *config,
45 Time *config_timestamp);
46 XRRScreenSize *XRRConfigSizes(
48 XRRScreenConfiguration *config,
49 int *nsizes);
50 short *XRRConfigRates (
52 XRRScreenConfiguration *config,
53 int size_index,
54 int *nrates);
55 SizeID XRRConfigCurrentConfiguration (
57 XRRScreenConfiguration *config,
58 Rotation *rotation);
59 short XRRConfigCurrentRate (
61 XRRScreenConfiguration *config);
62 int XRRRootToScreen(
64 Display *dpy,
65 Window root);
66 void XRRSelectInput(Display *dpy, Window window, int mask);
68 /∗
70 * intended to take RRScreenChangeNotify, or
71 * ConfigureNotify (on the root window)
72 * returns 1 if it is an event type it understands, 0 if not
73 */
74 int XRRUpdateConfiguration(XEvent *event);
75 /∗
77 * the following are always safe to call, even if RandR is
78 * not implemented on a screen
79 */
80 Rotation XRRRotations(
81 Display *dpy, int screen,
82 Rotation *current_rotation);
83 XRRScreenSize *XRRSizes(Display *dpy,
85 int screen, int *nsizes);
86 short *XRRRates (Display *dpy, int screen,
88 int size_index, int *nrates);
89 Time XRRTimes (Display *dpy, int screen, Time *config_timestamp);
91
93 display Specifies the connection to the X server.
94 screen Specifies which screen.
96 draw Specifies the screen.
98 rotation Specifies the possible rotations or reflections of the
100 screen.
101 current_rotation
103 Specifies the current rotations and reflection of the screen.
104 timestamp Specifies the server timestamp.
106 config_timestamp
108 Specifies the timestamp when the screen was last (re)config‐
109 ured.
110 config Specifies the screen configuration being used.
112 sizes Specifies the array of supported sizes.
114 rate Specifies the refresh rate in Hz.
116
119 Rotations/Reflections
120 Can be any of:
122 #define RR_Rotate_0 1
123 #define RR_Rotate_90 2
124 #define RR_Rotate_180 4
125 #define RR_Rotate_270 8
126 /∗ new in 1.0 protocol, to allow reflection of screen */
128 /∗ reflection is applied after rotation */
129 #define RR_Reflect_X 16
131 #define RR_Reflect_Y 32
132 typedef struct {
135 int width, height;
136 int mwidth, mheight;
137 } XRRScreenSize;
138 typedef struct {
140 int type; /∗ event base */
141 unsigned long serial; /∗ # of last request processed by server */
142 Bool send_event; /∗ true if this came from a SendEvent request */
143 Display *display; /∗ Display the event was read from */
144 Window window; /∗ window which selected for this event */
145 Window root; /∗ Root window for changed screen */
146 Time timestamp; /∗ when the screen change occurred */
147 Time config_timestamp; /∗ when the last configuration change */
148 SizeID size_index;
149 SubpixelOrder subpixel_order;
150 Rotation rotation;
151 int width;
152 int height;
153 int mwidth;
154 int mheight;
155 } XRRScreenChangeNotifyEvent;
156 The XRRScreenSize structure contains a possible root size in pixels and
158 in millimeters.
159 A XRRScreenChangeNotifyEvent is sent to a client that has requested
161 notification whenever the screen configuration is changed. A client can
162 perform this request by calling XRRSelectInput, passing the display,
163 the root window, and the RRScreenChangeNotifyMask mask.
164 XRRScreenConfiguration is an opaque data type containing the configura‐
166 tion information for a screen.
167 Timestamps
169 Time stamps are included and must be used to ensure the client is play‐
171 ing with a full deck: the screen may change properties on the fly and
172 this ensures its knowledge of the configuration is up to date. This is
173 to help issues when screens may become hot-pluggable in the future.
174
177 Xrandr is a simple library designed to interface the X Resize and
178 Rotate Extension. This allows clients to change the size and rotation
179 of the root window of a screen, along with the ability to reflect the
180 screen about either axis (if supported by the implementation). Rota‐
181 tion and reflection may be implemented by software and may result in
182 slower performance if rotation and reflection are implemented in this
183 fashion (as are all implementations as of October 2002).
184 The Xrandr library does some minimal caching to avoid roundtrips to
186 provide clients frequently used information. See "The X Resize and
187 Rotate Extension" for a detailed description; also note that depth
188 switching, as described in the document is not implemented, and may (or
189 may not) ever be implemented, as display memory is growing rapidly, and
190 toolkits are already beginning to support migration, mitigating the
191 need for depth switching. If it is implemented in the future, we
192 expect to do so via an upward compatible extension to the current
193 library/protocol; functionality described here should continue to work.
194 Rotation and reflection and how they interact can be confusing. In
196 Randr, the coordinate system is rotated in a counter-clockwise direc‐
197 tion relative to the normal orientation. Reflection is along the win‐
198 dow system coordinate system, not the physical screen X and Y axis, so
199 that rotation and reflection do not interact. The other way to con‐
200 sider reflection is to treat it as specified in the "normal" orienta‐
201 tion, before rotation.
202 The XRRScreenChangeNotify event is sent to clients that ask to be
204 informed whenever the root window configuration changes. Configuration
205 changes may include resolution, physical size, subpixel order (see
206 XRender(3)), and rotation. Note that changes to any or all of these
207 could occur due to external events (user control in the X server, a
208 different monitor/flat panel display being hot-plugged) and is not only
209 the result of a protocol/library request to the X server.
210 Additionally, to eliminate a potential race condition, this event may
212 be generated immediately upon selecting for notification if the screen
213 has changed since the client of Xrandr connected to the X server, to
214 enable reliable screen resolution changing when a user may log in and
215 change the configuration while one or many clients are starting up.
216 Xlib notification
218 Clients must call back into Xlib using XRRUpdateConfiguration when
220 screen configuration change notify events are generated (or root window
221 configuration changes occur, to update Xlib's view of the resolution,
222 size, rotation, reflection or subpixel order. Generally, toolkits will
223 perform this operation on behalf of applications; we did not want to
224 change display structure data behind the back of toolkits, as in multi‐
225 threaded clients, various race conditions might occur. Toolkits should
226 provide clients some mechanism for notification of screen change, of
227 course.
228
231 There are two classes of interfaces: those which can be safely called
232 even if RandR is not implemented on a screen (to make common idioms not
233 dependent on the server having support), and those which will return
234 errors if the extension is not present.
235 XRRRotations returns both the possible set of rotations/reflections
237 supported (as a bitmask) as the value of the function, along with the
238 current rotation/reflection of the screen.
239 XRRSizes returns the size and a pointer to the current sizes supported
241 by the specified screen. The first size specified is the default size
242 of the server. If RandR is not supported, it returns 0 for the number
243 of sizes.
244 XRRRates returns a pointer to the rates supported by the specified
246 size. If RandR is not supported, it returns 0 for the number of rates.
247 XRRTimes returns the time last reported by the server along with the
249 timestamp the last configuration changed. If the configuration has
250 changed since the client last updated its view of the server time,
251 requests to change the configuration will fail until the client has an
252 up to date timestamp.
253 XRRRootToScreen returns the screen number given a root window (for
255 example, from an XRRScreenChangeNotifyEvent).
256 The rest of the functions will fail if applied to screens not imple‐
258 menting the RandR extension. XRRSetScreenConfig sets the screen size
259 and rotation and reflection to the desired values on the screen speci‐
260 fied by draw, or returns a BadValue error. size_index specifies which
261 size configuration is to be used, rotation specifies which rotation or
262 reflection is to be used (or a BadValue error is returned). The time‐
263 stamp is used by the server to make sure the client has up to date con‐
264 figuration information. Status is returned to indicate success or fail‐
265 ure; a client must refresh its configuration information if it fails
266 and try the call again (by calling XRRGetScreenInfo).
267 XRRSetScreenConfigAndRate is like XRRSetScreenConfig but also sets the
269 refresh rate. If specified rate is not supported a BadValue error is
270 returned.
271 XRRConfigRotations, XRRConfigSizes, XRRConfigCurrentConfiguration,
273 XRRConfigTimes, XRRConfigRates, and XRRConfigCurrentRate are used to
274 get specific configuration information out of a screen configuration.
275 XRRGetScreenInfo returns a screen configuration for later use; the
277 information is private to the library. Call XRRFreeScreenConfigInfo to
278 free this information when you are finished with it. It forces a round
279 trip to the server.
280 Other functions include: XRRQueryExtension which returns the event and
282 error base codes, XRRQueryVersion , which returns the current version
283 of the extension (this information is cached by the library).
284
286 Xrandr will remain upward compatible after the current 1.0 release.
287
289 Jim Gettys, and Keith Packard, HP.
290X Version 11 libXrandr 1.5.2 XRANDR(3)