1XRANDR(3)                  Library Functions Manual                  XRANDR(3)
2
3
4

NAME

6        Xrandr - X Resize, Rotate and Reflection extension.
7

SYNTAX

9       #include <X11/extensions/Xrandr.h>
10
11       Bool XRRQueryExtension (Display *dpy,
12            int *event_base_return, int *error_base_return);
13
14       Status XRRQueryVersion (Display *dpy,
15            int *major_version_return,
16            int *minor_version_return);
17
18       XRRScreenConfiguration *XRRGetScreenInfo (Display *dpy,
19            Drawable draw);
20
21       void XRRFreeScreenConfigInfo (
22            XRRScreenConfiguration *config);
23
24       Status XRRSetScreenConfig (Display *dpy,
25            XRRScreenConfiguration *config,
26            Drawable draw,
27            int size_index,
28            Rotation rotation,
29            Time timestamp);
30
31       Status XRRSetScreenConfigAndRate (Display *dpy,
32                             XRRScreenConfiguration *config,
33                             Drawable draw,
34                             int size_index,
35                             Rotation rotation,
36                             short rate,
37                             Time timestamp);
38
39       Rotation XRRConfigRotations(
40            XRRScreenConfiguration *config,
41            Rotation *current_rotation);
42
43       Time XRRConfigTimes (
44            XRRScreenConfiguration *config,
45            Time *config_timestamp);
46
47       XRRScreenSize *XRRConfigSizes(
48            XRRScreenConfiguration *config,
49            int *nsizes);
50
51       short *XRRConfigRates (
52            XRRScreenConfiguration *config,
53            int size_index,
54            int *nrates);
55
56       SizeID XRRConfigCurrentConfiguration (
57            XRRScreenConfiguration *config,
58            Rotation *rotation);
59
60       short XRRConfigCurrentRate (
61            XRRScreenConfiguration *config);
62
63       int XRRRootToScreen(
64            Display *dpy,
65            Window root);
66
67       void XRRSelectInput(Display *dpy, Window window, int mask);
68
69       /∗
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
76       /∗
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
84       XRRScreenSize *XRRSizes(Display *dpy,
85            int screen, int *nsizes);
86
87       short *XRRRates (Display *dpy, int screen,
88            int size_index, int *nrates);
89
90       Time XRRTimes (Display *dpy, int screen, Time *config_timestamp);
91

ARGUMENTS

93       display   Specifies the connection to the X server.
94
95       screen    Specifies which screen.
96
97       draw      Specifies the screen.
98
99       rotation  Specifies  the  possible  rotations  or  reflections  of  the
100                 screen.
101
102       current_rotation
103                 Specifies the current rotations and reflection of the screen.
104
105       timestamp Specifies the server timestamp.
106
107       config_timestamp
108                 Specifies the timestamp when the screen was last  (re)config‐
109                 ured.
110
111       config    Specifies the screen configuration being used.
112
113       sizes     Specifies the array of supported sizes.
114
115       rate      Specifies the refresh rate in Hz.
116
117

DATATYPES

119       Rotations/Reflections
120
121       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
127       /∗ new in 1.0 protocol, to allow reflection of screen */
128       /∗ reflection is applied after rotation */
129
130       #define RR_Reflect_X            16
131       #define RR_Reflect_Y            32
132
133
134       typedef struct {
135           int   width, height;
136           int   mwidth, mheight;
137       } XRRScreenSize;
138
139       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
157       The XRRScreenSize structure contains a possible root size in pixels and
158       in millimeters.
159
160       A XRRScreenChangeNotifyEvent is sent to a client that has requested no‐
161       tification  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
165       XRRScreenConfiguration is an opaque data type containing the configura‐
166       tion information for a screen.
167
168       Timestamps
169
170       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
175

DESCRIPTION

177       Xrandr  is  a simple library designed to interface the X Resize and Ro‐
178       tate Extension.  This allows clients to change the size and rotation of
179       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
185       The  Xrandr  library  does  some minimal caching to avoid roundtrips to
186       provide clients frequently used information.  See "The X Resize and Ro‐
187       tate  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 ex‐
192       pect to do so via an upward compatible extension  to  the  current  li‐
193       brary/protocol; functionality described here should continue to work.
194
195       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
203       The  XRRScreenChangeNotify  event is sent to clients that ask to be in‐
204       formed 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
211       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
217       Xlib notification
218
219       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
229

FUNCTIONS

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
236       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
240       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
245       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
248       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,  re‐
251       quests to change the configuration will fail until the client has an up
252       to date timestamp.
253
254       XRRRootToScreen returns the screen number given a root window (for  ex‐
255       ample, from an XRRScreenChangeNotifyEvent).
256
257       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
268       XRRSetScreenConfigAndRate is like XRRSetScreenConfig but also sets  the
269       refresh  rate.  If  specified rate is not supported a BadValue error is
270       returned.
271
272       XRRConfigRotations, XRRConfigSizes, XRRConfigCurrentConfiguration,  XR‐
273       RConfigTimes,  XRRConfigRates, and XRRConfigCurrentRate are used to get
274       specific configuration information out of a screen configuration.
275
276       XRRGetScreenInfo returns a screen configuration for later use; the  in‐
277       formation  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
281       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

RESTRICTIONS

286       Xrandr will remain upward compatible after the current 1.0 release.
287

AUTHOR

289       Jim Gettys, and Keith Packard, HP.
290
291
292
293
294X Version 11                    libXrandr 1.5.4                      XRANDR(3)
Impressum