2 .\" Copyright 2001 Keith Packard
4 .\" Permission to use, copy, modify, distribute, and sell this software and its
5 .\" documentation for any purpose is hereby granted without fee, provided that
6 .\" the above copyright notice appear in all copies and that both that
7 .\" copyright notice and this permission notice appear in supporting
8 .\" documentation, and that the name of Keith Packard not be used in
9 .\" advertising or publicity pertaining to distribution of the software without
10 .\" specific, written prior permission. Keith Packard makes no
11 .\" representations about the suitability of this software for any purpose. It
12 .\" is provided "as is" without express or implied warranty.
14 .\" KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
15 .\" INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
16 .\" EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
17 .\" CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
18 .\" DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
19 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
20 .\" PERFORMANCE OF THIS SOFTWARE.
23 .\" $XFree86: xc/programs/xrandr/xrandr.man,v 1.6 2003/06/12 14:12:39 eich Exp $
25 .TH XRANDR __appmansuffix__ __vendorversion__
27 xrandr \- primitive command line interface to RandR extension
30 [\-help] [\-display \fIdisplay\fP]
34 [\-\-screen \fIsnum\fP]
38 .B RandR version 1.3 options
45 [\-\-panning \fIwidth\fPx\fIheight\fP[+\fIx\fP+\fIy\fP[/\fItrack_width\fPx\fItrack_height\fP+\fItrack_x\fP+\fItrack_y\fP[/\fIborder_left\fP/\fIborder_top\fP/\fIborder_right\fP/\fIborder_bottom\fP]]]]
46 [\-\-scale \fIx\fPx\fIy\fP]
47 [\-\-transform \fIa\fP,\fIb\fP,\fIc\fP,\fId\fP,\fIe\fP,\fIf\fP,\fIg\fP,\fIh\fP,\fIi\fP]
50 .B RandR version 1.2 options
53 [\-\-fb \fIwidth\fPx\fIheight\fP]
54 [\-\-fbmm \fIwidth\fPx\fIheight\fP]
56 [\-\-newmode \fIname\fP \fImode\fP]
57 [\-\-rmmode \fIname\fP]
58 [\-\-addmode \fIoutput\fP \fIname\fP]
59 [\-\-delmode \fIoutput\fP \fIname\fP]
63 [\-\-output \fIoutput\fP]
67 [\-\-pos \fIx\fPx\fIy\fP]
69 [\-\-reflect \fIreflection\fP]
70 [\-\-rotate \fIorientation\fP]
71 [\-\-left\-of \fIoutput\fP\]
72 [\-\-right\-of \fIoutput\fP\]
73 [\-\-above \fIoutput\fP\]
74 [\-\-below \fIoutput\fP\]
75 [\-\-same-as \fIoutput\fP\]
76 [\-\-set \fIproperty\fP \fIvalue\fP]
79 [\-\-gamma \fIred\fP:\fIgreen\fP:\fIblue\fP]
80 [\-\-brightness \fIbrightness\fP]
83 .B RandR version 1.0 and version 1.1 options
85 [\-o \fIorientation\fP]
91 is used to set the size, orientation and/or reflection of the outputs for a
92 screen. It can also set the screen size.
94 If invoked without any option, it will dump the state of the outputs,
95 showing the existing modes for each of them, with a '+' after the preferred
96 mode and a '*' after the current mode.
98 There are a few global options. Other options modify the last output that is
99 specified in earlier parameters in the command line. Multiple outputs may
100 be modified at the same time by passing multiple \-\-output options followed
101 immediately by their corresponding modifying options.
103 Print out a summary of the usage and exit.
104 .IP "\-v, \-\-version"
105 Print out the RandR version reported by the X server and exit.
107 Causes xrandr to be more verbose. When used with \-q (or without other
108 options), xrandr will display more information about the server state. When
109 used along with options that reconfigure the system, progress will be
110 reported while executing the configuration changes.
112 When this option is present, or when no configuration changes are requested,
113 xrandr will display the current state of the system.
115 Performs all the actions specified except that no changes are made.
117 Apply the modifications without grabbing the screen. It avoids to block other
118 applications during the update but it might also cause some applications that
119 detect screen resize to receive old values.
120 .IP "\-d, \-display \fIname\fP"
121 This option selects the X display to use. Note this refers to the X
122 screen abstraction, not the monitor (or output).
123 .IP "\-\-screen \fIsnum\fP"
124 This option selects which screen to manipulate. Note this refers to the X
125 screen abstraction, not the monitor (or output).
127 Forces the usage of the RandR version 1.1 protocol, even if a higher version
130 Forces the usage of the RandR version 1.2 protocol, even if the display does
131 not report it as supported or a higher version is available.
133 .SH "RandR version 1.3 options"
135 Options for RandR 1.3 are used as a superset of the options for RandR 1.2.
138 Return the current screen configuration, without polling for hardware changes.
140 Don't define a primary output.
142 .B "Per-output options"
143 .IP "\-\-panning \fIwidth\fPx\fIheight\fP[+\fIx\fP+\fIy\fP[/\fItrack_width\fPx\fItrack_height\fP+\fItrack_x\fP+\fItrack_y\fP[/\fIborder_left\fP/\fIborder_top\fP/\fIborder_right\fP/\fIborder_bottom\fP]]]"
144 This option sets the panning parameters. As soon as panning is
145 enabled, the CRTC position can change with every pointer move.
146 The first four parameters specify the total panning area, the next four the
147 pointer tracking area (which defaults to the same area). The last four
148 parameters specify the border and default to 0. A width or height set to zero
149 disables panning on the according axis. You typically have to set the screen
150 size with \fI--fb\fP simultaneously.
151 .IP "\-\-transform \fIa\fP,\fIb\fP,\fIc\fP,\fId\fP,\fIe\fP,\fIf\fP,\fIg\fP,\fIh\fP,\fIi\fP"
152 Specifies a transformation matrix to apply on the output. Automatically a bilinear filter is selected.
153 The mathematical form corresponds to:
162 The transformation is based on homogeneous coordinates. The matrix multiplied
163 by the coordinate vector of a pixel of the output gives the transformed
164 coordinate vector of a pixel in the graphic buffer. More precisely, the vector
166 of the output pixel is extended to 3 values
168 with 1 as the w coordinate and multiplied against the matrix. The final device
169 coordinates of the pixel are then calculated with the so-called homogenic
170 division by the transformed w coordinate. In other words, the device
173 of the transformed pixel are:
175 x' = (ax + by + c) / w' and
177 y' = (dx + ey + f) / w' ,
179 with w' = (gx + hy + i) .
181 Typically, \fIa\fP and
182 \fIe\fP corresponds to the scaling on the X and Y axes, \fIc\fP and \fIf\fP
183 corresponds to the translation on those axes, and \fIg\fP, \fIh\fP, and \fIi\fP
184 are respectively 0, 0 and 1. The matrix can also be used to express more
185 complex transformations such as keystone shaping, or rotation. For a
186 rotation of an angle T, this formula can be used:
194 As a special argument, instead of
195 passing a matrix, one can pass the string \fInone\fP, in which case the default
196 values are used (a unit matrix without filter).
198 .IP "\-\-scale \fIx\fPx\fIy\fP"
199 Changes the dimensions of the output picture. Values superior to 1 will lead to
200 a compressed screen (screen dimension bigger than the dimension of the output
201 mode), and values below 1 leads to a zoom in on the output. This option is
202 actually a shortcut version of the \fI\-\-transform\fP option.
204 Set the output as primary.
205 It will be sorted first in Xinerama and RANDR geometry requests.
207 .SH "RandR version 1.2 options"
208 These options are only available for X server supporting RandR version 1.2
210 .IP "\-\-prop, \-\-properties"
211 This option causes xrandr to display the contents of properties for each
212 output. \-\-verbose also enables \-\-prop.
213 .IP "\-\-fb \fIwidth\fPx\fIheight\fP"
214 Reconfigures the screen to the specified size. All configured monitors must
215 fit within this size. When this option is not provided, xrandr computes the
216 smallest screen size that will hold the set of configured outputs; this
217 option provides a way to override that behaviour.
218 .IP "\-\-fbmm \fIwidth\fPx\fIheight\fP"
219 Sets the reported values for the physical size of the screen. Normally,
220 xrandr resets the reported physical size values to keep the DPI constant.
221 This overrides that computation.
222 .IP "\-\-dpi \fIdpi\fP"
223 This also sets the reported physical size values of the screen, it uses the
224 specified DPI value to compute an appropriate physical size using whatever
225 pixel size will be set.
226 .IP "\-\-newmode \fIname\fP \fImode\fP"
227 New modelines can be added to the server and then associated with outputs.
228 This option does the former. The \fImode\fP is specified using the ModeLine
229 syntax for xorg.conf: hdisp hsyncstart hsyncend htotal vdisp vsyncstart
230 vsyncend vtotal \fIflags\fP. \fIflags\fP can be zero or more of +HSync,
231 -HSync, +VSync, -VSync, Interlace, DoubleScan, CSync, +CSync, -CSync. Several
232 tools permit to compute the usual modeline from a height, width, and refresh
233 rate, for instance you can use \fBcvt\fR.
234 .IP "\-\-rmmode \fIname\fP"
235 This removes a mode from the server if it is otherwise unused.
236 .IP "\-\-addmode \fIoutput\fP \fIname\fP"
237 Add a mode to the set of valid modes for an output.
238 .IP "\-\-delmode \fIoutput\fP \fIname\fP"
239 Remove a mode from the set of valid modes for an output.
241 .B "Per-output options"
242 .IP "\-\-output \fIoutput\fP"
243 Selects an output to reconfigure. Use either the name of the output or the
246 For connected but disabled outputs, this will enable them using their
247 preferred mode (or, something close to 96dpi if they have no preferred
248 mode). For disconnected but enabled outputs, this will disable them.
249 .IP "\-\-mode \fImode\fP"
250 This selects a mode. Use either the name or the XID for \fImode\fP
252 This selects the same mode as \-\-auto, but it doesn't automatically enable or
254 .IP "\-\-pos \fIx\fPx\fIy\fP"
255 Position the output within the screen using pixel coordinates. In case reflection
256 or rotation is applied, the translation is applied after the effects.
257 .IP "\-\-rate \fIrate\fP"
258 This marks a preference for refresh rates close to the specified value, when
259 multiple modes have the same name, this will select the one with the nearest
261 .IP "\-\-reflect \fIreflection\fP"
262 Reflection can be one of 'normal' 'x', 'y' or 'xy'. This causes the output
263 contents to be reflected across the specified axes.
264 .IP "\-\-rotate \fIrotation\fP"
265 Rotation can be one of 'normal', 'left', 'right' or 'inverted'. This causes
266 the output contents to be rotated in the specified direction. 'right' specifies
267 a clockwise rotation of the picture and 'left' specifies a counter-clockwise
269 .IP "\-\-left\-of, \-\-right\-of, \-\-above, \-\-below, \-\-same-as \fIanother-output\fP"
270 Use one of these options to position the output relative to the position of
271 another output. This allows convenient tiling of outputs within the screen.
272 The position is always computed relative to the new position of the other
273 output, so it is not valid to say \-\-output a \-\-left\-of b \-\-output
275 .IP "\-\-set \fIproperty\fP \fIvalue\fP"
276 Sets an output property. Integer properties may be specified as a valid
277 (see \-\-prop) decimal or hexadecimal (with a leading 0x) value. Atom properties
278 may be set to any of the valid atoms (see \-\-prop). String properties may be
282 .IP "\-\-crtc \fIcrtc\fP"
283 Uses the specified crtc (either as an index in the list of CRTCs or XID).
284 In normal usage, this option is not required as xrandr tries to make
285 sensible choices about which crtc to use with each output. When that fails
286 for some reason, this option can override the normal selection.
287 .IP "\-\-gamma \fIred\fP:\fIgreen\fP:\fIblue\fP"
288 Set the specified floating point values as gamma correction on the crtc
289 currently attached to this output. Note that you cannot get two different values
290 for cloned outputs and that switching an output to another crtc doesn't change
291 the crtc gamma corrections at all.
292 .IP "\-\-brightness \fIbrightness\fP"
293 Multiply the gamma values on the crtc currently attached to the output to
294 specified floating value. Useful for overly bright or overly dim outputs.
296 .SH "RandR version 1.1 options"
297 These options are available for X servers supporting RandR version 1.1 or
298 older. They are still valid for newer X servers, but they don't interact
299 sensibly with version 1.2 options on the same command line.
300 .IP "\-s, \-\-size \fIsize-index\fP or \-\-size \fIwidth\fPx\fIheight\fP"
301 This sets the screen size, either matching by size or using the index into
302 the list of available sizes.
303 .IP "\-r, \-\-rate, \-\-refresh \fIrate\fP"
304 This sets the refresh rate closest to the specified value.
305 .IP "\-o, \-\-orientation \fIrotation\fP"
306 This specifies the orientation of the screen,
307 and can be one of normal, inverted, left or right.
309 Reflect across the X axis.
311 Reflect across the Y axis.
313 Sets an output called LVDS to its preferred mode, and on its right put an
314 output called VGA to preferred mode of a screen which has been physically rotated clockwise:
316 xrandr --output LVDS --auto --rotate normal --pos 0x0 --output VGA --auto --rotate left --right-of LVDS
319 Forces to use a 1024x768 mode on an output called VGA:
321 xrandr --newmode "1024x768" 63.50 1024 1072 1176 1328 768 771 775 798 -hsync +vsync
323 xrandr --addmode VGA 1024x768
325 xrandr --output VGA --mode 1024x768
328 Enables panning on a 1600x768 desktop while displaying 1024x768 mode on an output called VGA:
330 xrandr --fb 1600x768 --output VGA --mode 1024x768 --panning 1600x0
333 Have one small 1280x800 LVDS screen showing a small version of a huge 3200x2000 desktop, and have a
334 big VGA screen display the surrounding of the mouse at normal size.
336 xrandr --fb 3200x2000 --output LVDS --scale 2.5x2.5 --output VGA --pos 0x0 --panning 3200x2000+0+0/3200x2000+0+0/64/64/64/64
339 Displays the VGA output in keystone shape so that it is projected correctly
340 when the beamer is slightly above the screen:
342 xrandr --fb 1024x768 --output VGA --transform 1.24,0.16,-124,0,1.24,0,0,0.000316,1
345 Xrandr(3), cvt(1), xkeystone(1)
348 Open Source Technology Center, Intel Corporation.
351 Cambridge Research Laboratory, HP Labs, HP.
projects / xorg / xrandr / blob