1XRANDR(1) General Commands Manual XRANDR(1)
2
6 xrandr - primitive command line interface to RandR extension
7
9 xrandr [--help] [--display display] [-q] [-v] [--verbose] [--dryrun]
10 [--screen snum] [--q1] [--q12] [--current] [--noprimary] [--panning
11 widthxheight[+x+y[/track_widthxtrack_height+track_x+track_y[/bor‐
12 der_left/border_top/border_right/border_bottom]]]] [--scale xxy]
13 [--scale-from wxh] [--transform a,b,c,d,e,f,g,h,i] [--primary] [--prop]
14 [--fb widthxheight] [--fbmm widthxheight] [--dpi dpi] [--newmode name
15 mode] [--rmmode name] [--addmode output name] [--delmode output name]
16 [--output output] [--auto] [--mode mode] [--preferred] [--pos xxy]
17 [--rate rate] [--reflect reflection] [--rotate orientation] [--left-of
18 output] [--right-of output] [--above output] [--below output] [--same-
19 as output] [--set property value] [--off] [--crtc crtc] [--gamma
20 red:green:blue] [--brightness brightness] [-o orientation] [-s size]
21 [-r rate] [-x] [-y] [--listproviders] [--setprovideroutputsource
22 provider source] [--setprovideroffloadsink provider sink]
23
25 Xrandr is used to set the size, orientation and/or reflection of the
26 outputs for a screen. It can also set the screen size.
27 If invoked without any option, it will dump the state of the outputs,
29 showing the existing modes for each of them, with a '+' after the pre‐
30 ferred modes and a '*' after the current mode.
31 There are a few global options. Other options modify the last output
33 that is specified in earlier parameters in the command line. Multiple
34 outputs may be modified at the same time by passing multiple --output
35 options followed immediately by their corresponding modifying options.
36 --help Print out a summary of the usage and exit.
38 -v, --version
40 Print out the RandR version reported by the X server and exit.
41 --verbose
43 Causes xrandr to be more verbose. When used with -q (or without
44 other options), xrandr will display more information about the
45 server state. Please note that the gamma and brightness informa‐
46 tions are only approximations of the complete color profile
47 stored in the server. When used along with options that recon‐
48 figure the system, progress will be reported while executing the
49 configuration changes.
50 -q, --query
52 When this option is present, or when no configuration changes
53 are requested, xrandr will display the current state of the sys‐
54 tem.
55 --dryrun
57 Performs all the actions specified except that no changes are
58 made.
59 --nograb
61 Apply the modifications without grabbing the screen. It avoids
62 to block other applications during the update but it might also
63 cause some applications that detect screen resize to receive old
64 values.
65 -d, --display name
67 This option selects the X display to use. Note this refers to
68 the X screen abstraction, not the monitor (or output).
69 --screen snum
71 This option selects which screen to manipulate. Note this refers
72 to the X screen abstraction, not the monitor (or output).
73 --q1 Forces the usage of the RandR version 1.1 protocol, even if a
75 higher version is available.
76 --q12 Forces the usage of the RandR version 1.2 protocol, even if the
78 display does not report it as supported or a higher version is
79 available.
80
82 Options for RandR 1.4 are used as a superset of the options for RandR
83 1.3.
84 --listproviders
86 Report information about the providers available.
87 --setprovideroutputsource provider source
89 Set source as the source of display output images for provider.
90 This is only possible if source and provider have the Source
91 Output and Sink Output capabilities, respectively. If source is
92 0x0, then provider is disconnected from its current output
93 source.
94 --setprovideroffloadsink provider sink
96 Set provider as a render offload device for sink. This is only
97 possible if provider and sink have the Source Offload and Sink
98 Offload capabilities, respectively. If sink is 0x0, then
99 provider is disconnected from its current render offload sink.
100
102 Options for RandR 1.3 are used as a superset of the options for RandR
103 1.2.
104 --current
106 Return the current screen configuration, without polling for
107 hardware changes.
108 --noprimary
110 Don't define a primary output.
111 Per-output options
113 --panning widthxheight[+x+y[/track_widthx‐
115 track_height+track_x+track_y[/border_left/border_top/border_right/bor‐
116 der_bottom]]]
117 This option sets the panning parameters. As soon as panning is
118 enabled, the CRTC position can change with every pointer move.
119 The first four parameters specify the total panning area, the
120 next four the pointer tracking area (which defaults to the same
121 area). The last four parameters specify the border and default
122 to 0. A width or height set to zero disables panning on the
123 according axis. You typically have to set the screen size with
124 --fb simultaneously.
125 --transform a,b,c,d,e,f,g,h,i
127 Specifies a transformation matrix to apply on the output. Auto‐
128 matically a bilinear filter is selected. The mathematical form
129 corresponds to:
130 a b c
131 d e f
132 g h i
133 The transformation is based on homogeneous coordinates. The
134 matrix multiplied by the coordinate vector of a pixel of the
135 output gives the transformed coordinate vector of a pixel in the
136 graphic buffer. More precisely, the vector (x y) of the output
137 pixel is extended to 3 values (x y w), with 1 as the w coordi‐
138 nate and multiplied against the matrix. The final device coordi‐
139 nates of the pixel are then calculated with the so-called
140 homogenic division by the transformed w coordinate. In other
141 words, the device coordinates (x' y') of the transformed pixel
142 are:
143 x' = (ax + by + c) / w' and
144 y' = (dx + ey + f) / w' ,
145 with w' = (gx + hy + i) .
146 Typically, a and e corresponds to the scaling on the X and Y
147 axes, c and f corresponds to the translation on those axes, and
148 g, h, and i are respectively 0, 0 and 1. The matrix can also be
149 used to express more complex transformations such as keystone
150 correction, or rotation. For a rotation of an angle T, this
151 formula can be used:
152 cos T -sin T 0
153 sin T cos T 0
154 0 0 1
155 As a special argument, instead of passing a matrix, one can pass
156 the string none, in which case the default values are used (a
157 unit matrix without filter).
158 --scale xxy
160 Changes the dimensions of the output picture. Values superior to
161 1 will lead to a compressed screen (screen dimension bigger than
162 the dimension of the output mode), and values below 1 leads to a
163 zoom in on the output. This option is actually a shortcut ver‐
164 sion of the --transform option.
165 --scale-from wxh
167 Specifies the size in pixels of the area of the framebuffer to
168 be displayed on this output. This option is actually a shortcut
169 version of the --transform option.
170 --primary
172 Set the output as primary. It will be sorted first in Xinerama
173 and RANDR geometry requests.
174
176 These options are only available for X server supporting RandR version
177 1.2 or newer.
178 --prop, --properties
180 This option causes xrandr to display the contents of properties
181 for each output. --verbose also enables --prop.
182 --fb widthxheight
184 Reconfigures the screen to the specified size. All configured
185 monitors must fit within this size. When this option is not pro‐
186 vided, xrandr computes the smallest screen size that will hold
187 the set of configured outputs; this option provides a way to
188 override that behaviour.
189 --fbmm widthxheight
191 Sets the reported values for the physical size of the screen.
192 Normally, xrandr resets the reported physical size values to
193 keep the DPI constant. This overrides that computation.
194 --dpi dpi
196 This also sets the reported physical size values of the screen,
197 it uses the specified DPI value to compute an appropriate physi‐
198 cal size using whatever pixel size will be set.
199 --newmode name mode
201 New modelines can be added to the server and then associated
202 with outputs. This option does the former. The mode is speci‐
203 fied using the ModeLine syntax for xorg.conf: clock hdisp hsync‐
204 start hsyncend htotal vdisp vsyncstart vsyncend vtotal flags.
205 flags can be zero or more of +HSync, -HSync, +VSync, -VSync,
206 Interlace, DoubleScan, CSync, +CSync, -CSync. Several tools per‐
207 mit to compute the usual modeline from a height, width, and
208 refresh rate, for instance you can use cvt.
209 --rmmode name
211 This removes a mode from the server if it is otherwise unused.
212 --addmode output name
214 Add a mode to the set of valid modes for an output.
215 --delmode output name
217 Remove a mode from the set of valid modes for an output.
218 Per-output options
220 --output output
222 Selects an output to reconfigure. Use either the name of the
223 output or the XID.
224 --auto For connected but disabled outputs, this will enable them using
226 their first preferred mode (or, something close to 96dpi if they
227 have no preferred mode). For disconnected but enabled outputs,
228 this will disable them.
229 --mode mode
231 This selects a mode. Use either the name or the XID for mode
232 --preferred
234 This selects the same mode as --auto, but it doesn't automati‐
235 cally enable or disable the output.
236 --pos xxy
238 Position the output within the screen using pixel coordinates.
239 In case reflection or rotation is applied, the translation is
240 applied after the effects.
241 --rate rate
243 This marks a preference for refresh rates close to the specified
244 value, when multiple modes have the same name, this will select
245 the one with the nearest refresh rate.
246 --reflect reflection
248 Reflection can be one of 'normal' 'x', 'y' or 'xy'. This causes
249 the output contents to be reflected across the specified axes.
250 --rotate rotation
252 Rotation can be one of 'normal', 'left', 'right' or 'inverted'.
253 This causes the output contents to be rotated in the specified
254 direction. 'right' specifies a clockwise rotation of the picture
255 and 'left' specifies a counter-clockwise rotation.
256 --left-of, --right-of, --above, --below, --same-as another-output
258 Use one of these options to position the output relative to the
259 position of another output. This allows convenient tiling of
260 outputs within the screen. The position is always computed rel‐
261 ative to the new position of the other output, so it is not
262 valid to say --output a --left-of b --output b --left-of a.
263 --set property value
265 Sets an output property. Integer properties may be specified as
266 a valid (see --prop) comma-separated list of decimal or hexadec‐
267 imal (with a leading 0x) values. Atom properties may be set to
268 any of the valid atoms (see --prop). String properties may be
269 set to any value.
270 --off Disables the output.
272 --crtc crtc
274 Uses the specified crtc (either as an index in the list of CRTCs
275 or XID). In normal usage, this option is not required as xrandr
276 tries to make sensible choices about which crtc to use with each
277 output. When that fails for some reason, this option can over‐
278 ride the normal selection.
279 --gamma red:green:blue
281 Set the specified floating point values as gamma correction on
282 the crtc currently attached to this output. Note that you cannot
283 get two different values for cloned outputs (i.e.: which share
284 the same crtc) and that switching an output to another crtc
285 doesn't change the crtc gamma corrections at all.
286 --brightness brightness
288 Multiply the gamma values on the crtc currently attached to the
289 output to specified floating value. Useful for overly bright or
290 overly dim outputs. However, this is a software only modifica‐
291 tion, if your hardware has support to actually change the
292 brightness, you will probably prefer to use xbacklight.
293
295 These options are available for X servers supporting RandR version 1.1
296 or older. They are still valid for newer X servers, but they don't
297 interact sensibly with version 1.2 options on the same command line.
298 -s, --size size-index or --size widthxheight
300 This sets the screen size, either matching by size or using the
301 index into the list of available sizes.
302 -r, --rate, --refresh rate
304 This sets the refresh rate closest to the specified value.
305 -o, --orientation rotation
307 This specifies the orientation of the screen, and can be one of
308 normal, inverted, left or right.
309 -x Reflect across the X axis.
311 -y Reflect across the Y axis.
313
315 Sets an output called LVDS to its preferred mode, and on its right put
316 an output called VGA to preferred mode of a screen which has been phys‐
317 ically rotated clockwise:
318 xrandr --output LVDS --auto --rotate normal --pos 0x0 --output
319 VGA --auto --rotate left --right-of LVDS
320 Forces to use a 1024x768 mode on an output called VGA:
322 xrandr --newmode "1024x768" 63.50 1024 1072 1176 1328 768 771
323 775 798 -hsync +vsync
324 xrandr --addmode VGA 1024x768
325 xrandr --output VGA --mode 1024x768
326 Enables panning on a 1600x768 desktop while displaying 1024x768 mode on
328 an output called VGA:
329 xrandr --fb 1600x768 --output VGA --mode 1024x768 --panning
330 1600x0
331 Have one small 1280x800 LVDS screen showing a small version of a huge
333 3200x2000 desktop, and have a big VGA screen display the surrounding of
334 the mouse at normal size.
335 xrandr --fb 3200x2000 --output LVDS --scale 2.5x2.5 --output VGA
336 --pos 0x0 --panning 3200x2000+0+0/3200x2000+0+0/64/64/64/64
337 Displays the VGA output in trapezoid shape so that it is keystone cor‐
339 rected when the projector is slightly above the screen:
340 xrandr --fb 1024x768 --output VGA --transform
341 1.24,0.16,-124,0,1.24,0,0,0.000316,1
342
344 Xrandr(3), cvt(1), xkeystone(1), xbacklight(1)
345
347 Keith Packard, Open Source Technology Center, Intel Corporation. and
348 Jim Gettys, Cambridge Research Laboratory, HP Labs, HP.
349X Version 11 xrandr 1.5.0 XRANDR(1)