Chapter 18. Programming Modes
Prev | Part I. Installation and Configuration Instructions | Next

## Chapter 18. Programming Modes

The NVIDIA Accelerated FreeBSD 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 FreeBSD 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:

     # 1024x768i @ 87Hz (industry standard)
     ModeLine "1024x768"  44.9  1024 1032 1208 1264  768 768 776 817 +hsync +vsync Interlace

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:

        # 1024x768 @ 120.00 Hz (GTF) hsync: 98.76 kHz; pclk: 139.05 MHz
        Modeline "1024x768_120"  139.05  1024 1104 1216 1408  768 769 772 823 -HSync +Vsync

Then, in the Screen section of your X config file, specify a MetaMode like this:

        Option "MetaModes" "1024x768_120, 1024x768_120"

### Additional Information

An XFree86 ModeLine generator, conforming to the GTF Standard is available at http://gtf.sourceforge.net/. Additional generators can be found by searching for "modeline" on freshmeat.net.

Prev | Up | Next
Chapter 17. Configuring a Notebook | Home | Chapter 19. Configuring Flipping and UBB