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 rotations or reflections possible 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 sizes supported.
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 XRRScreenSize structure contains a possible root size in pixels and in
158 millimeters. XRRScreenChangeNotifyEvent Is sent to a client that has
159 requested notification whenever the screen configuration is changed.
160 XRRScreenConfiguration This is an opaque data type containing the con‐
162 figuration information for a screen.
163 Timestamps
165 Time stamps are included and must be used to ensure the client is play‐
167 ing with a full deck: the screen may change properties on the fly and
168 this ensures its knowledge of the configuration is up to date. This is
169 to help issues when screens may become hot-pluggable in the future.
170
173 Xrandr is a simple library designed to interface the X Resize and
174 Rotate Extension. This allows clients to change the size and rotation
175 of the root window of a screen, along with the ability to reflect the
176 screen about either axis (if supported by the implementation). Rota‐
177 tion and reflection may be implemented by software and may result in
178 slower performance if rotation and reflection are implemented in this
179 fashion (as are all implementations as of October 2002).
180 The Xrandr library does some minimal caching to avoid roundtrips to
182 provide clients frequently used information. See "The X Resize and
183 Rotate Extension" for a detailed description; also note that depth
184 switching, as described in the document is not implemented, and may (or
185 may not) ever be implemented, as display memory is growing rapidly, and
186 toolkits are already beginning to support migration, mitigating the
187 need for depth switching. If it is implemented in the future, we
188 expect to do so via an upward compatible extension to the current
189 library/protocol; functionality described here should continue to work.
190 Rotation and reflection and how they interact can be confusing. In
192 Randr, the coordinate system is rotated in a counter-clockwise direc‐
193 tion relative to the normal orientation. Reflection is along the win‐
194 dow system coordinate system, not the physical screen X and Y axis, so
195 that rotation and reflection do not interact. The other way to con‐
196 sider reflection is to is specified in the "normal" orientation, before
197 rotation, if you find the other way confusing.
198 The XRRScreenChangeNotify event is sent to clients that ask to be
200 informed whenever the root window configuration changes. Configuration
201 changes may include resolution, physical size, subpixel order (see
202 XRender(3)), and rotation. Note that changes to any or all of these
203 could occur due to external events (user control in the X server, a
204 different monitor/flat panel display being hot-plugged) and is not only
205 the result of a protocol/library request to the X server.
206 Additionally, to eliminate a potential race condition, this event may
208 be generated immediately upon selecting for notification if the screen
209 has changed since the client of Xrandr connected to the X server, to
210 enable reliable screen resolution changing when a user may log in and
211 change the configuration while one or many clients are starting up.
212 Xlib notification
214 Clients must call back into Xlib using XRRUpdateConfiguration when
216 screen configuration change notify events are generated (or root window
217 configuration changes occur, to update Xlib's view of the resolution,
218 size, rotation, reflection or subpixel order. Generally, toolkits will
219 perform this operation on behalf of applications; we did not want to
220 change display structure data behind the back of toolkits, as in multi‐
221 threaded clients, various race conditions might occur. Toolkits should
222 provide clients some mechanism for notification of screen change, of
223 course.
224
227 There are two classes of interfaces: those which can be safely called
228 even if RandR is not implemented on a screen (to make common idioms not
229 dependent on the server having support), and those which will return
230 errors if the extension is not present.
231 XRRRotations returns both the possible set of rotations/reflections
233 supported (as a bitmask) as the value of the function, along with the
234 current rotation/reflection of the screen.
235 XRRSizes returns the size and a pointer to the current sizes supported
237 by the specified screen. The first size specified is the default size
238 of the server. If RandR is not supported, it returns 0 for the number
239 of sizes.
240 XRRRates returns a pointer to a the rates supported by the specified
242 size. If RandR is not supported, it returns 0 for the number of rates.
243 XRRTimes returns the time last reported by the server along with the
245 timestamp the last configuration changed. If the configuration has
246 changed since the client last updated its view of the server time,
247 requests to change the configuration will fail until the client has an
248 up to date timestamp.
249 XRRRootToScreen returns the screen number given a root window (for
251 example, from an XRRScreenChangeNotifyEvent.
252 The rest of the functions will fail if applied to screens not imple‐
254 menting the RandR extension. XRRSetScreenConfig sets the screen size
255 and rotation and reflection to the desired values on the screen speci‐
256 fied by draw, or returns a BadValue error. size_index specifies which
257 size configuration is to be used, rotation specifies which rotation or
258 reflection is to be used (or a BadValue error is returned). The time‐
259 stamp is used by the server to make sure the client has up to date con‐
260 figuration information. Status is returned to indicate success or fail‐
261 ure; a client must refresh its configuration information if it fails
262 and try the call again (by calling XRRGetScreenInfo).
263 XRRSetScreenConfigAndRate like XRRSetScreenConfig but also set the
265 refresh rate. If specified rate is not supported a BadValue error is
266 returned.
267 XRRConfigRotations, XRRConfigSizes, XRRConfigCurrentConfiguration,
269 XRRConfigTimes, XRRConfigRates, and XRRConfigCurrentRate are used to
270 get specific configuration information out of a screen configuration.
271 XRRGetScreenInfo Returns a screen configuration for later use; the
273 information is private to the library. Call XRRFreeScreenConfigInfo to
274 free this information when you are finished with it. It forces a round
275 trip to the server.
276 Other functions include: XRRQueryExtension which returns the event and
278 error base codes, XRRQueryVersion , which returns the current version
279 of the extension (this information is cached by the library).
280
282 Xrandr will remain upward compatible after the current 1.0 release.
283
285 Jim Gettys, and Keith Packard, HP.
286X Version 11 libXrandr 1.3.0 XRANDR(3)