Chapter 19. Programming Modes

The NVIDIA Accelerated Linux Graphics Driver supports all
standard VGA and VESA modes, as well as most user-written custom
mode lines; double-scan and interlaced modes are supported on all
GPUs supported by the NVIDIA driver.

To request one or more standard modes for use in X, you can
simply add a "Modes" line such as:

Modes "1600x1200" "1024x768" "640x480"

in the appropriate Display subsection of your X config file (see
the XF86Config(5x) or xorg.conf(5x) man pages for details). Or, the
nvidia-xconfig(1) utility can be used to request additional modes;
for example:

nvidia-xconfig --mode 1600x1200

See the nvidia-xconfig(1) man page for details.

Depth, Bits per Pixel, and Pitch

While not directly a concern when programming modes, the bits
used per pixel is an issue when considering the maximum
programmable resolution; for this reason, it is worthwhile to
address the confusion surrounding the terms "depth" and "bits per
pixel". Depth is how many bits of data are stored per pixel.
Supported depths are 8, 15, 16, and 24. Most video hardware,
however, stores pixel data in sizes of 8, 16, or 32 bits; this is
the amount of memory allocated per pixel. When you specify your
depth, X selects the bits per pixel (bpp) size in which to store
the data. Below is a table of what bpp is used for each possible
depth:

Depth

BPP

8

8

15

16

16

16

24

32

Lastly, the "pitch" is how many bytes in the linear frame buffer
there are between one pixel's data, and the data of the pixel
immediately below. You can think of this as the horizontal
resolution multiplied by the bytes per pixel (bits per pixel
divided by 8). In practice, the pitch may be more than this product
due to alignment constraints.

Maximum Resolutions

The NVIDIA Accelerated Linux Graphics Driver and NVIDIA
GPU-based graphics cards support resolutions up to 16384x16384
pixels for the GeForce GTX 400 series and newer GPUs, 8192x8192
pixels for the GeForce 8 series and above, and up to 4096x4096
pixels for the GeForce 7 series and below, though the maximum
resolution your system can support is also limited by the amount of
video memory (see USEFUL FORMULAS for details) and the maximum
supported resolution of your display device (monitor/flat
panel/television). Also note that while use of a video overlay does
not limit the maximum resolution or refresh rate, video memory
bandwidth used by a programmed mode does affect the overlay
quality.

Useful Formulas

The maximum resolution is a function both of the amount of video
memory and the bits per pixel you elect to use:

HR * VR * (bpp/8) = Video Memory
Used

In other words, the amount of video memory used is equal to the
horizontal resolution (HR) multiplied by the vertical resolution
(VR) multiplied by the bytes per pixel (bits per pixel divided by
eight). Technically, the video memory used is actually the pitch
times the vertical resolution, and the pitch may be slightly
greater than (HR *
(bpp/8)) to accommodate the hardware requirement that
the pitch be a multiple of some value.

Note that this is just memory usage for the frame buffer; video
memory is also used by other things, such as OpenGL and pixmap
caching.

Another important relationship is that between the resolution,
the pixel clock (also known as the dot clock) and the vertical
refresh rate:

RR = PCLK / (HFL * VFL)

In other words, the refresh rate (RR) is equal to the pixel
clock (PCLK) divided by the total number of pixels: the horizontal
frame length (HFL) multiplied by the vertical frame length (VFL)
(note that these are the frame lengths, and not just the visible
resolutions). As described in the XFree86 Video Timings HOWTO, the
above formula can be rewritten as:

PCLK = RR * HFL * VFL

Given a maximum pixel clock, you can adjust the RR, HFL and VFL
as desired, as long as the product of the three is consistent. The
pixel clock is reported in the log file. Your X log should contain
a line like this:

(--) NVIDIA(0): ViewSonic VPD150 (DFP-1): 165 MHz maximum pixel clock

which indicates the maximum pixel clock for that display
device.

How Modes Are Validated

In traditional XFree86/X.Org mode validation, the X server takes
as a starting point the X server's internal list of VESA standard
modes, plus any modes specified with special ModeLines in the X
configuration file's Monitor section. These modes are validated
against criteria such as the valid HorizSync/VertRefresh frequency
ranges for the user's monitor (as specified in the Monitor section
of the X configuration file), as well as the maximum pixel clock of
the GPU.

Once the X server has determined the set of valid modes, it
takes the list of user requested modes (i.e., the set of modes
named in the "Modes" line in the Display subsection of the Screen
section of X configuration file), and finds the "best" validated
mode with the requested name.

The NVIDIA X driver uses a variation on the above approach to
perform mode validation. During X server initialization, the NVIDIA
X driver builds a pool of valid modes for each display device. It
gathers all possible modes from several sources:

The display device's EDID

The X server's built-in list

Any user-specified ModeLines in the X configuration file

The VESA standard modes

For every possible mode, the mode is run through mode
validation. The core of mode validation is still performed
similarly to traditional XFree86/X.Org mode validation: the mode
timings are checked against things such as the valid HorizSync and
VertRefresh ranges and the maximum pixelclock. Note that each
individual stage of mode validation can be independently controlled
through the "ModeValidation" X configuration option.

Note that when validating interlaced mode timings, VertRefresh
specifies the field rate, rather than the frame rate. For example,
the following modeline has a vertical refresh rate of 87 Hz:

Invalid modes are discarded; valid modes are inserted into the
mode pool. See MODE VALIDATION REPORTING for how to get more
details on mode validation results for each considered mode.

Valid modes are given a unique name that is guaranteed to be
unique across the whole mode pool for this display device. This
mode name is constructed approximately like this:

<width>x<height>_<refreshrate>

(e.g., "1600x1200_85")

The name may also be prepended with another number to ensure the
mode is unique; e.g., "1600x1200_85_0".

As validated modes are inserted into the mode pool, duplicate
modes are removed, and the mode pool is sorted, such that the
"best" modes are at the beginning of the mode pool. The sorting is
based roughly on:

Resolution

Source (EDID-provided modes are prioritized higher than
VESA-provided modes, which are prioritized higher than modes that
were in the X server's built-in list)

Refresh rate

Once modes from all mode sources are validated and the mode pool
is constructed, all modes with the same resolution are compared;
the best mode with that resolution is added to the mode pool a
second time, using just the resolution as its unique modename
(e.g., "1600x1200"). In this way, when you request a mode using the
traditional names (e.g., "1600x1200"), you still get what you got
before (the 'best' 1600x1200 mode); the added benefit is that all
modes in the mode pool can be addressed by a unique name.

When verbose logging is enabled (see the FAQ section on increasing the amount of
data printed in the X log file), the mode pool for each display
device is printed to the X log file.

After the mode pool is built for all display devices, the
requested modes (as specified in the X configuration file), are
looked up from the mode pool. Each requested mode that can be
matched against a mode in the mode pool is then advertised to the X
server and is available to the user through the X server's mode
switching hotkeys (ctrl-alt-plus/minus) and the XRandR and
XF86VidMode X extensions.

If only one display device is in use by the X screen when the X
server starts, all modes in the mode pool are implicitly made
available to the X server. See the "IncludeImplicitMetaModes" X
configuration option in Appendix B, X
Config Options for details.

The NVIDIA-Auto-Select Mode

You can request a special mode by name in the X config file,
named "nvidia-auto-select". When the X driver builds the mode pool
for a display device, it selects one of the modes as the
"nvidia-auto-select" mode; a new entry is made in the mode pool,
and "nvidia-auto-select" is used as the unique name for the
mode.

The "nvidia-auto-select" mode is intended to be a reasonable
mode for the display device in question. For example, the
"nvidia-auto-select" mode is normally the native resolution for
flat panels, as reported by the flat panel's EDID, or one of the
detailed timings from the EDID. The "nvidia-auto-select" mode is
guaranteed to always be present, and to always be defined as
something considered valid by the X driver for this display
device.

Note that the "nvidia-auto-select" mode is not necessarily the
largest possible resolution, nor is it necessarily the mode with
the highest refresh rate. Rather, the "nvidia-auto-select" mode is
selected such that it is a reasonable default. The selection
process is roughly:

If the EDID for the display device reported a preferred mode
timing, and that mode timing is considered a valid mode, then that
mode is used as the "nvidia-auto-select" mode. You can check if the
EDID reported a preferred timing by starting X with logverbosity
greater than or equal to 5 (see the FAQ section on increasing the amount of
data printed in the X log file), and looking at the EDID printout;
if the EDID contains a line:

Prefer first detailed timing : Yes

Then the first mode listed under the "Detailed Timings" in the
EDID will be used.

If the EDID did not provide a preferred timing, the best
detailed timing from the EDID is used as the "nvidia-auto-select"
mode.

If the EDID did not provide any detailed timings (or there was
no EDID at all), the best valid mode not larger than 1024x768 is
used as the "nvidia-auto-select" mode. The 1024x768 limit is
imposed here to restrict use of modes that may have been validated,
but may be too large to be considered a reasonable default, such as
2048x1536.

If all else fails, the X driver will use a built-in 800 x 600
60Hz mode as the "nvidia-auto-select" mode.

If no modes are requested in the X configuration file, or none
of the requested modes can be found in the mode pool, then the X
driver falls back to the "nvidia-auto-select" mode, so that X can
always start. Appropriate warning messages will be printed to the X
log file in these fallback scenarios.

You can add the "nvidia-auto-select" mode to your X
configuration file by running the command

nvidia-xconfig --mode nvidia-auto-select

and restarting your X server.

The X driver can generally do a much better job of selecting the
"nvidia-auto-select" mode if the display device's EDID is
available. This is one reason why it is recommended to only use the
"UseEDID" X configuration option sparingly. Note that, rather than
globally disable all uses of the EDID with the "UseEDID" option,
you can individually disable each particular use of the EDID using
the "UseEDIDFreqs", "UseEDIDDpi", and/or the "NoEDIDModes" argument
in the "ModeValidation" X configuration option.

Mode Validation Reporting

When log verbosity is set to 6 or higher (see FAQ section on increasing the amount of
data printed in the X log file), the X log will record every mode
that is considered for each display device's mode pool, and report
whether the mode passed or failed. For modes that were considered
invalid, the log will report why the mode was considered
invalid.

Ensuring Identical Mode Timings

Some functionality, such as Active Stereo with TwinView,
requires control over exactly which mode timings are used. For
explicit control over which mode timings are used on each display
device, you can specify the ModeLine you want to use (using one of
the ModeLine generators available), and using a unique name. For
example, if you wanted to use 1024x768 at 120 Hz on each monitor in
TwinView with active stereo, you might add something like this to
the monitor section of your X configuration file: