1XRANDR(3x) XRANDR(3x)
2
6 Xrandr - X Resize, Rotate and Reflection extension.
7
9 #include <X11/extensions/Xrandr.h>
10 Bool XRRQueryExtension (Display *dpy,
12 int *event_basep, int *error_basep);
13 Status XRRQueryVersion (Display *dpy,
15 int *major_versionp,
16 int *minor_versionp);
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 XRRScreenConfiguration *XRRScreenConfig(
68 Display *dpy, int screen);
69 XRRScreenConfiguration *XRRConfig(Screen *screen);
71 void XRRSelectInput(Display *dpy, Window window, int mask);
73 /∗
75 * intended to take RRScreenChangeNotify, or
76 * ConfigureNotify (on the root window)
77 * returns 1 if it is an event type it understands, 0 if not
78 */
79 int XRRUpdateConfiguration(XEvent *event^);
80 /∗
82 * the following are always safe to call, even if RandR is
83 * not implemented on a screen
84 */
85 Rotation XRRRotations(
86 Display *dpy, int screen,
87 Rotation *current_rotation);
88 XRRScreenSize *XRRSizes(Display *dpy,
90 int screen, int *nsizes);
91 short *XRRRates (Display *dpy, int screen,
93 int size_index, int *nrates);
94 Time XRRTimes (Display *dpy, int screen, Time *config_timestamp);
96
98 display Specifies the connection to the X server.
99 screen Specifies which screen.
101 draw Specifies the screen.
103 rotation Specifies the rotations or reflections possible of the
105 screen.
106 current_rotation
108 Specifies the current rotations and reflection of the screen.
109 timestamp Specifies the server timestamp.
111 config_timestamp
113 Specifies the timestamp when the screen was last (re)config‐
114 ured.
115 config Specifies the screen configuration being used.
117 sizes Specifies the array of sizes supported.
119 rate Specifies the refresh rate in Hz.
121
124 Rotations/Reflections
125 Can be any of:
127 #define RR_Rotate_0 1
128 #define RR_Rotate_90 2
129 #define RR_Rotate_180 4
130 #define RR_Rotate_270 8
131 /∗ new in 1.0 protocol, to allow reflection of screen */
133 /∗ reflection is applied after rotation */
134 #define RR_Reflect_X 16
136 #define RR_Reflect_Y 32
137 typedef struct {
140 int width, height;
141 int mwidth, mheight;
142 } XRRScreenSize;
143 typedef struct {
145 int type; /∗ event base */
146 unsigned long serial; /∗ # of last request processed by server */
147 Bool send_event; /∗ true if this came from a SendEvent request */
148 Display *display; /∗ Display the event was read from */
149 Window window; /∗ window which selected for this event */
150 Window root; /∗ Root window for changed screen */
151 Time timestamp; /∗ when the screen change occurred */
152 Time config_timestamp; /∗ when the last configuration change */
153 SizeID size_index;
154 SubpixelOrder subpixel_order;
155 Rotation rotation;
156 int width;
157 int height;
158 int mwidth;
159 int mheight;
160 } XRRScreenChangeNotifyEvent;
161 XRRScreenSize structure contains a possible root size in pixels and in
163 millimeters. XRRScreenChangeNotifyEvent Is sent to a client that has
164 requested notification whenever the screen configuration is changed.
165 XRRScreenConfiguration This is an opaque data type containing the con‐
167 figuration information for a screen.
168 Timestamps
170 Time stamps are included and must be used to ensure the client is play‐
172 ing with a full deck: the screen may change properties on the fly and
173 this ensures its knowledge of the configuration is up to date. This is
174 to help issues when screens may become hot-pluggable in the future.
175
178 Xrandr is a simple library designed to interface the X Resize and
179 Rotate Extension. This allows clients to change the size and rotation
180 of the root window of a screen, along with the ability to reflect the
181 screen about either axis (if supported by the implementation). Rota‐
182 tion and reflection may be implemented by software and may result in
183 slower performance if rotation and reflection are implemented in this
184 fashion (as are all implementations as of October 2002).
185 The Xrandr library does some minimal caching to avoid roundtrips to
187 provide clients frequently used information. See "The X Resize and
188 Rotate Extension" for a detailed description; also note that depth
189 switching, as described in the document is not implemented, and may (or
190 may not) ever be implemented, as display memory is growing rapidly, and
191 toolkits are already beginning to support migration, mitigating the
192 need for depth switching. If it is implemented in the future, we
193 expect to do so via an upward compatible extension to the current
194 library/protocol; functionality described here should continue to work.
195 Rotation and reflection and how they interact can be confusing. In
197 Randr, the coordinate system is rotated in a counter-clockwise direc‐
198 tion relative to the normal orientation. Reflection is along the win‐
199 dow system coordinate system, not the physical screen X and Y axis, so
200 that rotation and reflection do not interact. The other way to con‐
201 sider reflection is to is specified in the "normal" orientation, before
202 rotation, if you find the other way confusing.
203 The XRRScreenChangeNotify event is sent to clients that ask to be
205 informed whenever the root window configuration changes. Configuration
206 changes may include resolution, physical size, subpixel order (see
207 XRender(3)), and rotation. Note that changes to any or all of these
208 could occur due to external events (user control in the X server, a
209 different monitor/flat panel display being hot-plugged) and is not only
210 the result of a protocol/library request to the X server.
211 Additionally, to eliminate a potential race condition, this event may
213 be generated immediately upon selecting for notification if the screen
214 has changed since the client of Xrandr connected to the X server, to
215 enable reliable screen resolution changing when a user may log in and
216 change the configuration while one or many clients are starting up.
217 Xlib notification
219 Clients must call back into Xlib using XRRUpdateConfiguration when
221 screen configuration change notify events are generated (or root window
222 configuration changes occur, to update Xlib's view of the resolution,
223 size, rotation, reflection or subpixel order. Generally, toolkits will
224 perform this operation on behalf of applications; we did not want to
225 change display structure data behind the back of toolkits, as in multi‐
226 threaded clients, various race conditions might occur. Toolkits should
227 provide clients some mechanism for notification of screen change, of
228 course.
229
232 There are two classes of interfaces: those which can be safely called
233 even if RandR is not implemented on a screen (to make common idioms not
234 dependent on the server having support), and those which will return
235 errors if the extension is not present.
236 XRRRotations returns both the possible set of rotations/reflections
238 supported (as a bitmask) as the value of the function, along with the
239 current rotation/reflection of the screen.
240 XRRSizes returns the size and a pointer to the current sizes supported
242 by the specified screen. The first size specified is the default size
243 of the server. If RandR is not supported, it returns 0 for the number
244 of sizes.
245 XRRRates returns a pointer to a the rates supported by the specified
247 size. If RandR is not supported, it returns 0 for the number of rates.
248 XRRTimes returns the time last reported by the server along with the
250 timestamp the last configuration changed. If the configuration has
251 changed since the client last updated its view of the server time,
252 requests to change the configuration will fail until the client has an
253 up to date timestamp.
254 XRRRootToScreen returns the screen number given a root window (for
256 example, from an XRRScreenChangeNotifyEvent.
257 The rest of the functions will fail if applied to screens not imple‐
259 menting the RandR extension. XRRSetScreenConfig sets the screen size
260 and rotation and reflection to the desired values on the screen speci‐
261 fied by draw, or returns a BadValue error. size_index specifies which
262 size configuration is to be used, rotation specifies which rotation or
263 reflection is to be used (or a BadValue error is returned). The time‐
264 stamp is used by the server to make sure the client has up to date con‐
265 figuration information. Status is returned to indicate success or fail‐
266 ure; a client must refresh its configuration information if it fails
267 and try the call again (by calling XRRGetScreenInfo).
268 XRRSetScreenConfigAndRate like XRRSetScreenConfig but also set the
270 refresh rate. If specified rate is not supported a BadValue error is
271 returned.
272 XRRConfigRotations, XRRConfigSizes, XRRConfigCurrentConfiguration,
274 XRRConfigTimes, XRRConfigRates, and XRRConfigCurrentRate are used to
275 get specific configuration information out of a screen configuration.
276 XRRGetScreenInfo Returns a screen configuration for later use; the
278 information is private to the library. Call XRRFreeScreenConfigInfo to
279 free this information when you are finished with it. It forces a round
280 trip to the server.
281 Other functions include: XRRQueryExtension which returns the event and
283 error base codes, XRRQueryVersion , which returns the current version
284 of the extension (this information is cached by the library).
285
287 Xrandr will remain upward compatible after the current 1.0 release.
288
290 Jim Gettys, and Keith Packard, HP.
291X Version 11 libXrandr 1.2.0 XRANDR(3x)