Chapter 12. Configuring Multiple Display Devices on One X Screen

Multiple display devices (digital flat panels, CRTs, and TVs) can display the contents of a single X screen in any arbitrary configuration. Configuring multiple display devices on a single X screen has several distinct advantages over other techniques (such as Xinerama):

If you are interested in using each display device as a separate X screen, see Chapter 14, Configuring Multiple X Screens on One Card.

Relevant X Configuration Options

When the NVIDIA X driver starts, by default it will enable as many display devices as are connected and as the GPU supports driving simultaneously. Most NVIDIA GPUs based on the Kepler architecture, or newer, support driving up to four display devices simultaneously. Most NVIDIA GPUs older than Kepler support driving up to two display devices simultaneously.

If multiple X screens are configured on the GPU, the NVIDIA X driver will attempt to reserve display devices and GPU resources for those other X screens (honoring the "UseDisplayDevice" and "MetaModes" X configuration options of each X screen) and then allocate all remaining resources to the first X screen configured on the GPU.

There are several X configuration options that influence how multiple display devices are used by an X screen:

    Option "MetaModes"                "<list of MetaModes>"

    Option "HorizSync"                "<hsync range(s)>"
    Option "VertRefresh"              "<vrefresh range(s)>"

    Option "MetaModeOrientation"      "<relationship of head 1 to head 0>"
    Option "ConnectedMonitor"         "<list of connected display devices>"

See detailed descriptions of each option below.

Detailed Description of Options

HorizSync, VertRefresh

With these options, you can specify a semicolon-separated list of frequency ranges, each optionally prepended with a display device name. In addition, if SLI Mosaic mode is enabled, a GPU specifier can be used. For example:

    Option "HorizSync"   "CRT-0: 50-110; DFP-0: 40-70"
    Option "VertRefresh" "CRT-0: 60-120; GPU-0.DFP-0: 60"

See Appendix C, Display Device Names on Display Device Names for more information.

These options are normally not needed: by default, the NVIDIA X driver retrieves the valid frequency ranges from the display device's EDID (see Appendix B, X Config Options for a description of the "UseEdidFreqs" option). The "HorizSync" and "VertRefresh" options override any frequency ranges retrieved from the EDID.

MetaModes

MetaModes are "containers" that store information about what mode should be used on each display device.

Multiple MetaModes list the combinations of modes and the sequence in which they should be used. In MetaMode syntax, modes within a MetaMode are comma separated, and multiple MetaModes are separated by semicolons. For example:

    "<mode name 0>, <mode name 1>; <mode name 2>, <mode name 3>"

Where <mode name 0> is the name of the mode to be used on display device 0 concurrently with <mode name 1> used on display device 1. A mode switch will then cause <mode name 2> to be used on display device 0 and <mode name 3> to be used on display device 1. Here is an example MetaMode:

    Option "MetaModes" "1280x1024,1280x1024; 1024x768,1024x768"

If you want a display device to not be active for a certain MetaMode, you can use the mode name "NULL", or simply omit the mode name entirely:

    "1600x1200, NULL; NULL, 1024x768"

or

    "1600x1200; , 1024x768"

Optionally, mode names can be followed by offset information to control the positioning of the display devices within the virtual screen space; e.g.,

    "1600x1200 +0+0, 1024x768 +1600+0; ..."

Offset descriptions follow the conventions used in the X "-geometry" command line option; i.e., both positive and negative offsets are valid, though negative offsets are only allowed when a virtual screen size is explicitly given in the X config file.

When no offsets are given for a MetaMode, the offsets will be computed following the value of the MetaModeOrientation option (see below). Note that if offsets are given for any one of the modes in a single MetaMode, then offsets will be expected for all modes within that single MetaMode; in such a case offsets will be assumed to be +0+0 when not given.

When not explicitly given, the virtual screen size will be computed as the the bounding box of all MetaMode bounding boxes. MetaModes with a bounding box larger than an explicitly given virtual screen size will be discarded.

A MetaMode string can be further modified with a "Panning Domain" specification; e.g.,

    "1024x768 @1600x1200, 800x600 @1600x1200"

A panning domain is the area in which a display device's viewport will be panned to follow the mouse. Panning actually happens on two levels with MetaModes: first, an individual display device's viewport will be panned within its panning domain, as long as the viewport is contained by the bounding box of the MetaMode. Once the mouse leaves the bounding box of the MetaMode, the entire MetaMode (i.e., all display devices) will be panned to follow the mouse within the virtual screen, unless the "PanAllDisplays" X configuration option is disabled. Note that individual display devices' panning domains default to being clamped to the position of the display devices' viewports, thus the default behavior is just that viewports remain "locked" together and only perform the second type of panning.

The most beneficial use of panning domains is probably to eliminate dead areas -- regions of the virtual screen that are inaccessible due to display devices with different resolutions. For example:

    "1600x1200, 1024x768"

produces an inaccessible region below the 1024x768 display. Specifying a panning domain for the second display device:

    "1600x1200, 1024x768 @1024x1200"

provides access to that dead area by allowing you to pan the 1024x768 viewport up and down in the 1024x1200 panning domain.

Offsets can be used in conjunction with panning domains to position the panning domains in the virtual screen space (note that the offset describes the panning domain, and only affects the viewport in that the viewport must be contained within the panning domain). For example, the following describes two modes, each with a panning domain width of 1900 pixels, and the second display is positioned below the first:

    "1600x1200 @1900x1200 +0+0, 1024x768 @1900x768 +0+1200"

Because it is often unclear which mode within a MetaMode will be used on each display device, mode descriptions within a MetaMode can be prepended with a display device name. For example:

    "CRT-0: 1600x1200,  DFP-0: 1024x768"

If no MetaMode string is specified, then the X driver uses the modes listed in the relevant "Display" subsection, attempting to place matching modes on each display device.

Each mode of the MetaMode may also have extra attributes associated with it, specified as a comma-separated list of token=value pairs inside curly brackets. The value for each token can optionally be enclosed in parentheses, to prevent commas within the value from being interpreted as token=value pair separators. Currently, the only token that requires a parentheses-enclosed value is "Transform".

The possible tokens within the curly bracket list are:

  • "Stereo": possible values are "PassiveLeft" or "PassiveRight". When used in conjunction with stereo mode "4", this allows each display to be configured independently to show any stereo eye. For example:

        "CRT-0: 1600x1200 +0+0 { Stereo = PassiveLeft }, CRT-1: 1600x1200 +1600+0 { Stereo=PassiveRight }"
    

    If the X screen is not configured for stereo mode "4", these options are ignored. See Option "Stereo" "integer" for more details about stereo configurations.

  • "Rotation": this rotates the content of an individual display device. Possible values are "0" (with synonyms "no", "off" and "normal"), "90" (with synonyms "left" and "CCW"), "180" (with synonyms "invert" and "inverted") and "270" (with synonyms "right" and "CW"). For example:

        "DFP-0: nvidia-auto-select { Rotation=left }, DFP-1: nvidia-auto-select { Rotation=right }"
    

    Independent rotation configurability of each display device is also possible through RandR. See Chapter 16, Support for the X Resize and Rotate Extension for details.

  • "Reflection": this reflects the content of an individual display device about either the X axis, the Y axis, or both the X and Y axes. Possible values are "X", "Y" and "XY". For example:

        "DFP-0: nvidia-auto-select { Reflection=X }, DFP-1: nvidia-auto-select"
    

    Independent reflection configurability of each display device is also possible through RandR. See Chapter 16, Support for the X Resize and Rotate Extension for details.

  • "Transform": this is a 3x3 matrix of floating point values that defines a transformation from the ViewPortOut for a display device to a region within the X screen. This is equivalent to the transformation matrix specified through the RandR 1.3 RRSetCrtcTransform request. As in RandR, the transform is applied before any specified rotation and reflection values to compute the complete transform.

    The 3x3 matrix is represented in the MetaMode syntax as a comma-separated list of nine floating point values, stored in row-major order. This is the same as the value passed to the xrandr(1) '--transform' command line option.

    Note that the transform value must be enclosed in parentheses, so that the commas separating the nine floating point values are interpreted correctly.

    For example:

        "DFP-0: nvidia-auto-select { Transform=(43.864288330078125, 21.333328247070312, -16384, 0, 43.864288330078125, 0, 0, 0.0321197509765625, 19.190628051757812) }"
    

  • "ViewPortOut": this specifies the region within the mode sent to the display device that will display pixels from the X screen. The region of the mode outside the ViewPortOut will contain black. The format is "WIDTH x HEIGHT +X +Y".

    This is useful, for example, for configuring overscan compensation. E.g., if the mode sent to the display device is 1920x1080, to configure a 10 pixel border on all four sides:

        "DFP-0: 1920x1080 { ViewPortOut=1900x1060+10+10 }"
    

    Or, to only display an image in the lower right quarter of the 1920x1080 mode:

        "DFP-0: 1920x1080 { ViewPortOut=960x540+960+540 }"
    

    When not specified, the ViewPortOut defaults to the size of the mode.

  • "ViewPortIn": this defines the size of the region of the X screen which will be displayed within the ViewPortOut. The format is "WIDTH x HEIGHT".

    ViewPortIn is useful for configuring scaling between the X screen and the display device. For example, to display an 800x600 region from the X screen on a 1920x1200 mode:

        "DFP-0: 1920x1200 { ViewPortIn=800x600 }"
    

    Or, to display a 2560x1600 region from the X screen on a 1920x1200 mode:

        "DFP-0: 1920x1200 { ViewPortIn=2560x1600 }"
    

    Or, in conjunction with ViewPortOut, to scale an 800x600 region of the X screen within a 1920x1200 mode while preserving the aspect ratio:

        "DFP-0: 1920x1200 { ViewPortIn=800x600, ViewPortOut=1600x1200+160+0 }"
    

    Scaling from ViewPortIn to ViewPortOut is also expressible through the "Transform" attribute. In fact, ViewPortIn is just a shortcut for populating the transformation matrix. If both ViewPortIn and Transform are specified in the MetaMode for a display device, ViewPortIn is ignored.

  • "PanningTrackingArea": this defines the region of the MetaMode inside which cursor movement will influence panning of the display device. The format is "WIDTH x HEIGHT + X + Y", to describe the size and offset of the region within the X screen. E.g.,

        "DFP-0: 1920x1200 +0+0 { PanningTrackingArea = 1920x1200 +0+0 }"
    

    If not specified in the MetaMode, this will default to the entire X screen. If the PanAllDisplays X configuration option is explicitly set to False, then PanningTrackingArea will default to the panning domain of the display device.

    This is equivalent to the panning tracking_area region in the RRSetPanning RandR 1.3 protocol request.

  • "PanningBorder": this defines the distances from the edges of the ViewPortIn that will activate panning if the pointer hits them. If the borders are 0, the display device will pan when the pointer hits the edge of the ViewPortIn (the default). If the borders are positive, the display device will pan when the pointer gets close to the edge of the ViewPortIn. If the borders are negative, the display device will pan when the pointer is beyond the edge of the ViewPortIn.

    The format is "LeftBorder/TopBorder/RightBorder/BottomBorder". E.g.,

        "DFP-0: 1920x1200 +0+0 { PanningBorder = 10/10/10/10 }"
    

    This is equivalent to the panning border in the RRSetPanning RandR 1.3 protocol request.

  • "ForceCompositionPipeline": possible values are "On" or "Off". The NVIDIA X driver can use a composition pipeline to apply X screen transformations and rotations. "ForceCompositionPipeline" can be used to force the use of this pipeline, even when no transformations or rotations are applied to the screen.

  • "ForceFullCompositionPipeline": possible values are "On" or "Off". This option implicitly enables "ForceCompositionPipeline" and additionally makes use of the composition pipeline to apply ViewPortOut scaling.

Note that the current MetaMode can also be configured through the NV-CONTROL X extension and the nvidia-settings utility. For example:

    nvidia-settings --assign CurrentMetaMode="DFP-0: 1920x1200 { ViewPortIn=800x600, ViewPortOut=1600x1200+160+0 }"

MetaModeOrientation

This option controls the positioning of the display devices within the virtual X screen, when offsets are not explicitly given in the MetaModes. The possible values are:

    "RightOf"  (the default)
    "LeftOf"
    "Above"
    "Below"
    "Clone"

When "Clone" is specified, all display devices will be assigned an offset of 0,0.

Because it is often unclear which display device relates to which, MetaModeOrientation can be confusing. You can further clarify the MetaModeOrientation with display device names to indicate which display device is positioned relative to which display device. For example:

    "CRT-0 LeftOf DFP-0"

ConnectedMonitor

With this option you can override what the NVIDIA kernel module detects is connected to your graphics card. This may be useful, for example, if any of your display devices do not support detection using Display Data Channel (DDC) protocols. Valid values are a comma-separated list of display device names; for example:

    "CRT-0, CRT-1"
    "CRT"
    "CRT-1, DFP-0"

WARNING: this option overrides what display devices are detected by the NVIDIA kernel module, and is very seldom needed. You really only need this if a display device is not detected, either because it does not provide DDC information, or because it is on the other side of a KVM (Keyboard-Video-Mouse) switch. In most other cases, it is best not to specify this option.

Just as in all X config entries, spaces are ignored and all entries are case insensitive.

Dynamic TwinView

Using the NV-CONTROL X extension, the display devices in use by an X screen, the mode pool for each display device, and the MetaModes for each X screen can be dynamically manipulated. The "Display Configuration" page in nvidia-settings uses this functionality to modify the MetaMode list and then uses XRandR to switch between MetaModes. This gives the ability to dynamically configure TwinView.

The details of how this works are documented in the nv-control-dpy.c sample NV-CONTROL client in the nvidia-settings source tarball.

Because the NVIDIA X driver can now transition into and out of TwinView dynamically, MetaModes are always used internally by the NVIDIA X driver, regardless of how many display devices are currently in use by the X screen and regardless of whether the TwinView X configuration option was specified.

One implication of this implementation is that each MetaMode must be uniquely identifiable to the XRandR X extension. Unfortunately, two MetaModes with the same bounding box will look the same to XRandR. For example, two MetaModes with different orientations:

    "CRT: 1600x1200 +0+0, DFP: 1600x1200 +1600+0"
    "CRT: 1600x1200 +1600+0, DFP: 1600x1200 +0+0"

will look identical to the XRandR or XF86VidMode X extensions, because they have the same total size (3200x1200), and nvidia-settings would not be able to use XRandR to switch between these MetaModes. To work around this limitation, the NVIDIA X driver "lies" about the refresh rate of each MetaMode, using the refresh rate of the MetaMode as a unique identifier.

The XRandR extension is currently being redesigned by the X.Org community, so the refresh rate workaround may be removed at some point in the future. This workaround can also be disabled by setting the "DynamicTwinView" X configuration option to FALSE, which will disable NV-CONTROL support for manipulating MetaModes, but will cause the XRandR and XF86VidMode visible refresh rate to be accurate.

12.1. Frequently Asked TwinView Questions

Nothing gets displayed on my second monitor; what is wrong?

Monitors that do not support monitor detection using Display Data Channel (DDC) protocols (this includes most older monitors) are not detectable by your NVIDIA card. You need to explicitly tell the NVIDIA X driver what you have connected using the "ConnectedMonitor" option; e.g.,

    Option "ConnectedMonitor" "CRT, CRT"

Will window managers be able to appropriately place windows (e.g., avoiding placing windows across both display devices, or in inaccessible regions of the virtual desktop)?

Yes. Window managers can query the layout of display devices through either RandR 1.2 or Xinerama.

The NVIDIA X driver provides a Xinerama extension that X clients (such as window managers) can use to discover the current layout of display devices. Note that the Xinerama protocol provides no way to notify clients when a configuration change occurs, so if you modeswitch to a different MetaMode, your window manager may still think you have the previous configuration. Using RandR 1.2, or the Xinerama extension in conjunction with the XF86VidMode extension to get modeswitch events, window managers should be able to determine the display device configuration at any given time.

Unfortunately, the data provided by XineramaQueryScreens() appears to confuse some window managers; to work around such broken window managers, you can disable communication of the display device layout with the "nvidiaXineramaInfo" X configuration option (see Appendix B, X Config Options for details).

The order that display devices are reported in via the NVIDIA Xinerama information can be configured with the nvidiaXineramaInfoOrder X configuration option.

Be aware that the NVIDIA driver cannot provide the Xinerama extension if the X server's own Xinerama extension is being used. Explicitly specifying Xinerama in the X config file or on the X server commandline will prohibit NVIDIA's Xinerama extension from installing, so make sure that the X server's log file does not contain:

    (++) Xinerama: enabled

if you want the NVIDIA driver to be able to provide the Xinerama extension while in TwinView.

Another solution is to use panning domains to eliminate inaccessible regions of the virtual screen (see the MetaMode description above).

A third solution is to use two separate X screens, rather than use TwinView. See Chapter 14, Configuring Multiple X Screens on One Card.

How are virtual screen dimensions determined in TwinView?

After all requested modes have been validated, and the offsets for each MetaMode's viewports have been computed, the NVIDIA driver computes the bounding box of the panning domains for each MetaMode. The maximum bounding box width and height is then found.

Note that one side effect of this is that the virtual width and virtual height may come from different MetaModes. Given the following MetaMode string:

    "1600x1200,NULL; 1024x768+0+0, 1024x768+0+768"

the resulting virtual screen size will be 1600 x 1536.

Can I play full screen games across both display devices?

Yes. While the details of configuration will vary from game to game, the basic idea is that a MetaMode presents X with a mode whose resolution is the bounding box of the viewports for that MetaMode. For example, the following:

    Option "MetaModes" "1024x768,1024x768; 800x600,800x600"
    Option "MetaModeOrientation" "RightOf"

produce two modes: one whose resolution is 2048x768, and another whose resolution is 1600x600. Games such as Quake 3 Arena use the VidMode extension to discover the resolutions of the modes currently available. To configure Quake 3 Arena to use the above MetaMode string, add the following to your q3config.cfg file:

    seta r_customaspect "1"
    seta r_customheight "600"
    seta r_customwidth  "1600"
    seta r_fullscreen   "1"
    seta r_mode         "-1"

Note that, given the above configuration, there is no mode with a resolution of 800x600 (remember that the MetaMode "800x600, 800x600" has a resolution of 1600x600"), so if you change Quake 3 Arena to use a resolution of 800x600, it will display in the lower left corner of your screen, with the rest of the screen grayed out. To have single head modes available as well, an appropriate MetaMode string might be something like:

    "800x600,800x600; 1024x768,NULL; 800x600,NULL; 640x480,NULL"

More precise configuration information for specific games is beyond the scope of this document, but the above examples coupled with numerous online sources should be enough to point you in the right direction.