Translation(s): none


The RandR 1.2 extension first appeared in Xserver 1.3 (i.e DebianTesting, since 2007-08-21). It provides automatic discovery of modes (resolutions, refresh rates, ...) together with the ability to configure outputs dynamically (resize, rotate, move, ...).

As of today, the following drivers/boards support RandR 1.2:

Other drivers still use the old/hard/non-standard way to configure modes.

I. Cleanup the Xinerama/MergedFB/... config

I.1. Remove options that the driver should query automatically

With the driver detecting modes automatically, several configuration options become useless most of the time in your configuration file (xorg.conf). You might want to remove:

I.2. Remove static dual-head configuration

Then, all dual-head related configuration should be removed, it includes:

See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=420419#27 and below for an example.

Sometimes, thanks to server autoconfiguration, it's also easier to just remove your xorg.conf entirely and see what happens.

II. Use xrandr to enable/disable/move/resize multiple outputs

II.1. Basics

Once the configuration file (xorg.conf) is updated, starting the server should enable some outputs by default. Their top-left corners will be at the same part of the image, but their modes will probably be different.

All outputs may be configured through xrandr (or the grandr graphic tool). To see the available outputs, just run xrandr:

  $ xrandr
  Screen 0: minimum 320 x 200, current 1400 x 1050, maximum 2048 x 1152
  VGA-0 disconnected (normal left inverted right x axis y axis)
  DVI-0 disconnected (normal left inverted right x axis y axis)
  LVDS connected 1400x1050+0+0 (normal left inverted right x axis y axis) 0mm x 0mm
     1400x1050      60.2*+
     1280x800       60.0
     1280x768       60.0
     1024x768       60.0   75.0
     800x600        60.3
     640x480        59.9
  S-video disconnected (normal left inverted right x axis y axis)

It shows that this board supports 4 outputs, names VGA-0, DVI-0, LVDS (the internal panel) and S-video (the TV output). Only LVDS is connected and it supports 6 modes at 60 Hz, and one at 75.

The mode marked with a star is the current mode.

The one marked with a plus is the preferred one. Most monitor report a preferred mode to the driver. And the server/driver will generally choose it by default.

II.2. Outputs naming convention

There are no standard naming convention as of today, it just depends on the driver, but it could change in the future.

At least the RadeonHD driver will print out a list of outputs as part of the /var/log/Xorg.0.log file generated by trying to start X. An example of output from the RadeonHD driver is

(II) RADEONHD(0): Output DVI-I_1/digital connected
(II) RADEONHD(0): Output DVI-I_1/analog disconnected
(II) RADEONHD(0): Output TV_7PIN_DIN disconnected
(II) RADEONHD(0): Output DVI-I_2/digital connected
(II) RADEONHD(0): Output DVI-I_2/analog disconnected

Where for example "DVI-I_1/digital" is the name of the digital output of the first DVI port.

For the internal laptop panel, external VGA, external DVI and TV, the drivers currently use:

When manipulating VGA-0 output properties as below, you should use:

  $ xrandr --output VGA-0 <options>

II.3. Adding/removing heads dynamically

The old days where you had to restart X when plugging a new monitor are gone. With RandR 1.2, you can plug/unplug monitors whenever you want. Running the following line will query all outputs and enable them with their default mode:

  $ xrandr --auto

You may also disable one output using:

  $ xrandr --output LVDS --off

This may be useful for some buggy application that don't support multiple outputs well. Also, due to CRTC limitations (see the Caveats section below), it is often required to disable one output before enabling another since most hardware only support 2 at the same time.

II.4. Changing the mode

With the above xrandr output, you may change the LVDS mode to 1024x768 using:

  $ xrandr --output LVDS --mode 1024x768

The refresh rate may also be changed, either at the same time or independently:

  $ xrandr --output LVDS --mode 1024x768 --rate 75

II.5. Placing outputs in a virtual screen

Randr 1.2 provides the ability to create a large virtual screen and place multiple output in it, either with or without overlapping zones. To reduce memory consumption, drivers will often create a default virtual screen with small dimensions, for instance 1600x1200. Look at the output of xrandr to know your virtual screen dimensions. It would be 2048x1152 if xrandr reports:

  $ xrandr
  Screen 0: minimum 320 x 200, current 1400 x 1050, maximum 2048 x 1152

If you plan to use multiple outputs displaying different zones, you should configure your xorg.conf by adding a Virtual line to subsection Display in the Screen section.

  Section "Screen"
    ...
    SubSection "Display"
      Depth 24
      Virtual 3000 2000
    EndSubSection
  EndSection

Then you place outputs using xrandr and the --right-of/--left-of/--above/--below options. For instance, to place your VGA output virtually-right of your internal panel, run:

  $ xrandr --output VGA --right-of LVDS

Note that hardware and memory limitations may severely restrict the size of your virtual screen, see the Caveats section below.

II.6. Adding new modes

Under some circumstances, some modes might be missing. For instance, if the monitor does not report correct EDID information. Or if the output didn't have a CRTC available at startup because another output was using it and you disabled it in th meantime.

If a mode exist, you may add it to one output with:

  $ xrandr --addmode S-video 800x600

If the mode does not exist, you may first create it by passing a modeline:

  $ xrandr --newmode <ModeLine>

You may create a modeline using the gtf or cvt utility.

If xrandr says it cannot find S-Video output, you might have to create a little xorg.conf file to help it:

Section "Device"
  Identifier "radeon"
  Driver "radeon"
  Option "ATOMTvOut" "true"
EndSection

III. xorg.conf based configuration

Running xrandr is convenient for dynamic configuration, but it may be annoying if you have to run it after every startup of your X server. Section III.6 summarizes all this by showing an example of modern configuration.

III.1. Per Output Config

Before configuring an output, you need to know how to specify it in the config file. To do so, you may add a Monitor-FOO option to the Device section to identify the monitor section for output FOO. For instance:

  Section "Device"
    Identifier "My Graphic Board"
    ...
    Option "Monitor-LVDS" "Internal Panel"
    Option "Monitor-VGA" "External VGA Monitor"
  EndSection
  Section "Monitor"
    Identifier "Internal Panel"
    ...
  EndSection
  Section "Monitor"
    Identifier "External VGA Monitor"
    ...
  EndSection

Then, all output-specific options should go in the corresponding Monitor section.

III.2. Placing outputs

Add the following line to place one monitor on the right of another one as xrandr --output FOO --right-of BAR would do:

  Section "Monitor"
    Identifier "FOO"
  EndSection
  Section "Monitor"
    Identifier "BAR"
    Option "RightOf" "FOO"
  EndSection

III.3. Changing DPI and DisplaySize

If your monitor size isn't detected correctly and thus generates a wrong DPI, you need to add a DisplaySize option to the corresponding monitor section. For output FOO, use:

  Section "Monitor"
    Identifier "MyMonitor"
    DisplaySize 304 228
  EndSection
  Section "Device"
    ...
    Option "Monitor-FOO" "MyMonitor"
  EndSection

III.4. Forcing outputs off or on

If for some reason one output of your graphic board is enabled while it should not, you might want to disable it (for instance because the number of CRTCs available is limited). To do so, add:

    Option "Ignore" "true"

If for some reason one output is disabled by the driver (for instance VGA-0 on Radeon Xpress 200 because load detection is not reliable in the driver yet), you might want to enable it by force. To do so, add:

    Option "Enable" "true"

Then, you might need to add modes since such an output may not query modes correctly. See "Forcing a preferred mode" to do so.

III.5. Forcing a preferred mode

This is one of rare cases where the ModeLine open is still useful these days. If the preferred mode reported by your monitor isn't the one you want by default, or if there is no preferred mode and the driver does not choose the right one, you might want to force another mode on an output.

Assuming you want to force 1280x1024 at 75Hz at startup, add something like the following to the Monitor section:

    Modeline "1280x1024_75.00"  138.54  1280 1368 1504 1728  1024 1025 1028 1069  -HSync +Vsync
    Option "PreferredMode" "1280x1024_75.00"

The ModeLine line may be obtained by looking at your current Xorg.0.log if the mode is already detected (when it appears in the output of xrandr). Or you may generate a new one using:

  $ gtf 1280 1024 75
  Modeline "1280x1024_75.00"  138.54  1280 1368 1504 1728  1024 1025 1028 1069  -HSync +Vsync

III.6. Example of modern configuration

Here's an example of xorg.conf for a ATI board with DVI-0 (with DisplaySize and preferred mode forced), LVDS (placed on the right of DVI-0) and VGA-0 (disabled) outputs.

Section "InputDevice"
        Identifier      "Generic Keyboard"
        Driver          "keyboard"
        Option          "CoreKeyboard"
        Option          "XkbRules"      "xorg"
        Option          "XkbModel"      "pc101"
        Option          "XkbLayout"     "us"
EndSection
Section "InputDevice"
        Identifier      "Configured Mouse"
        Driver          "mouse"
        Option          "CorePointer"
        Option          "Device"                "/dev/input/mice"
        Option          "Protocol"              "ImPS/2"
        Option          "Emulate3Buttons"       "true"
        Option          "ZAxisMapping"          "4 5"
EndSection
# external DVI with DisplaySize and preferred mode overriden
Section "Monitor"
    Identifier      "External DVI"
    DisplaySize     304 228
    Modeline "1280x1024_60.00"  108.88  1280 1360 1496 1712  1024 1025 1028 1060  -HSync +Vsync
    Option "PreferredMode" "1280x1024_60.00"
EndSection
# internal laptop panel to place on the right of DVI-0
Section "Monitor"
    Identifier      "Integrated LCD"
    Option          "RightOf" "External DVI"
EndSection
# disable VGA by default
Section "Monitor"
    Identifier      "VGA-0"
    Option "Ignore" "true"
EndSection
Section "Device"
    Identifier      "ATI Technologies, Inc. M22 [Radeon Mobility M300]"
    Driver          "ati"
    BusID           "PCI:1:0:0"
    Option          "AccelMethod"   "EXA"
    Option          "Monitor-DVI-0" "External DVI"
    Option          "Monitor-LVDS"  "Integrated LCD"
    # no need to specific Monitor-VGA-0, it uses the "VGA-0" identifier automatically
EndSection
Section "Screen"
    Identifier      "Default Screen"
    Device          "ATI Technologies, Inc. M22 [Radeon Mobility M300]"
    DefaultDepth    24
    SubSection "Display"
        Depth           24
        # big virtual screen to place
        Virtual         3072 1200
    EndSubSection
EndSection
Section "ServerLayout"
        Identifier      "Default Layout"
        Screen          "Default Screen"
        InputDevice     "Generic Keyboard"
        InputDevice     "Configured Mouse"
EndSection

IV. Debugging problems

IV.1. Monitor quirks

Some hardware do not report correct information, especially lots of monitors report wrong EDID. In this case, the server/driver might detect some incorrect modes or miss some of them. In some cases, you will not be able to get your desired large resolution. In some other cases, you could get a black screen.

The best solution might be to add a quirk in the X server to work around hardware problems. If this happens to you, you might want to report a bug at http://bugzilla.freedesktop.org and provide detailled information including a precise identifier for your monitor. See https://bugs.freedesktop.org/show_bug.cgi?id=11603 for an example.

IV.2. Remote RandR configuration

If for some reason your X server just gives a blank screen at startup, especially because of incorrect modes, it might look hard for you to fix it since you can't use a terminal within the broken X to fix X. Fortunately, xrandr supports configuration of distant servers, using either the DISPLAY environment variable or the -display option:

   xrandr -display :0.0 ...

This way, if you have access to a VT console (with Ctrl-Alt-F1) or (better) if you can log in remotely through ssh, you might manage to select a correct mode.

V. Output specific properties

Each output may have several specific properties. For instance, the TV output has a tv_standard property to choose between PAL and NTSC. To see the values of properties, you should run:

  $ xrandr --verbose
  tv_standard: ntsc

To change the TV standard, use something like:

  $ xrandr --output S-video --set tv_standard pal

Additionally, some drivers such as ATI as of 6.7.195 disabling load detection on the TV output since it leads to TV wrongly being detected as connected, and thus a CRTC being wasted.

  $ xrandr --verbose
  load_detection: 0 (0x00000000) range:  (0,1)

To reenable load-detection, just run

  $ xrandr --output S-video --set load_detection 1

Some modes might need to be added then, see section Adding new modes above.

There is currently no way to specify output properties from xorg.conf.

VI. Caveats

VI.1. Virtual screen size

The dimensions of the virtual screen (Virtual line in subsection Display) may be severely constrained by memory consumption.

Also, the hardware does not support unlimited coordinates. For instance, Intel boards up to i945 only support 2048 pixels in each direction. If you enable a larger virtual screen, DRI will be disabled and some problems may appear.

VI.2. CRTCs

Most hardware only have 2 CRTCs, which means they only have 2 rendering pipeline and thus may only display on 2 outputs at the same time. This is why you may have to disable one output before being able to enable another one.

See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=439322#52 for an example.

2 outputs may only use the same CRTC in clone mode, i.e. if they use the exact same mode.

Some outputs may also be restricted to some CRTC. xrandr --verbose gives information on which CRTC are available/used for each output. For instance, below, LVDS uses CRTC #0 and may not use any other one. VGA-0 uses none currently and may use #0 or #1.

  VGA-0 disconnected (normal left inverted right x axis y axis)
        CRTCs:      0 1
  LVDS connected 1400x1050+0+0 (0x50) normal (normal left inverted right x axis y axis) 0mm x 0mm
        CRTC:       0
        CRTCs:      0

In case of problems, xrandr --crtc may be used to force another CRTC for some output.

VI.3. XV Overlay on only one display

(This is not really new to RandR 1.2 but more people are experiencing this issue nowadays)

The hardware may only display the X-Video overlay (basically the image generated by video players) on one output at the same time. So, if a video window appears on two outputs at the same time, the X-Video content with only appear on one of them, the other monitor will keep a black image. To move the X-Video overlay to the second CRTC, use:

  xvattr -a XV_CRTC -v 1

(to move to the first CRTC, use -v 0).

The other way to solve this issue is to not have the same part of the screen on both outputs. The driver will automatically place the X-Video overlay on the CRTC where most of the X-Video window is.

VI.4. Old dual-head configs broken

RandR 1.2 aware drivers do not support old dual-head configs anymore. It will even crash the X server at startup.

VI.5. Multi-board support broken

RandR 1.2 does not support multiple boards yet (it's planned for RandR 1.3). It means that any RandR 1.2 aware driver will crash the server if you have 2 boards. Even one board with a RandR 1.2 driver and another board with a classic driver does not work. It just crashes the X server.

VI.6. No more multiple independent desktop

RandR 1.2 provides a big virtual screen where all outputs are placed. It is great if you like moving windows between monitors. But lots of people were used to have a single board with multiple independent monitors with one window manager on each of them. It's for instance nice if you want to switch between virtual desktops on one monitor without moving on the other one.

It is not possible anymore with RandR 1.2 unless the window manager implements it, which is pretty rare as of today (only Enlightenment 17, XMonad and awesome do it). As a small workaround, most window manager have the ability to pin a window on all virtual desktop, which implements N desktop on one head x 1 single desktop on the other head.

In case of multiple boards, it is not clear what will happen since RandR 1.2 does not support it yet (see the above section). Having a shared virtual screen between multiple boards might be hard.

See Also