MAN page from PLD nvidia-settings-295.40-1.i686.rpm

nvidia\-settings

Section: User Commands (1)
Updated: 2012-05-06
Index

NAME

nvidia-settings - configure the NVIDIA graphics driver

SYNOPSIS

nvidia-settings [options]
nvidia-settings [options] --no-config
nvidia-settings [options] --load-config-only
nvidia-settings [options] {--query=attr | --assign=attr=value} ...
nvidia-settings [options] --glxinfo

Options:[-vh] [--config=configfile] [-c ctrl-display]
[--verbose={errors | warnings | all}]
[--describe={all | list | attribute_name}]

attrhas the form:
DISPLAY/attribute_name[display_devices]

DESCRIPTION

Thenvidia-settingsutility is a tool for configuring the NVIDIA graphics driver.It operates by communicating with the NVIDIA X driver, querying and updating state as appropriate.This communication is done via the NV-CONTROL, GLX, XVideo, and RandR X extensions.

Values such as brightness and gamma, XVideo attributes, temperature, and OpenGL settings can be queried and configured vianvidia-settings.

Whennvidia-settingsstarts, it reads the current settings from its configuration file and sends those settings to the X server.Then, it displays a graphical user interface (GUI) for configuring the current settings.Whennvidia-settingsexits, it queries the current settings from the X server and saves them to the configuration file.

OPTIONS

-v, --version

Print the nvidia-settingsversion and exit.

-h, --help

Print usage information and exit.

--config=CONFIG

Use the configuration file CONFIGrather than the default ~/.nvidia-settings-rc

-c, --ctrl-display=CTRL-DISPLAY

Control the specified X display. If this option is not given, then nvidia-settingswill control the display specified by '--display'; if that is not given, then the $DISPLAYenvironment variable is used.

-l, --load-config-only

Load the configuration file, send the values specified therein to the X server, and exit. This mode of operation is useful to place in your xinitrc file, for example.

-n, --no-config

Do not load the configuration file. This mode of operation is useful if nvidia-settingshas difficulties starting due to problems with applying settings in the configuration file.

-r, --rewrite-config-file

Write the X server configuration to the configuration file, and exit, without starting the graphical user interface. See EXAMPLES section.

-V, --verbose=VERBOSE

Controls how much information is printed. By default, the verbosity is errorsand only error messages are printed. Valid values are 'none'(do not print messages), 'errors'(print error messages), 'warnings'(print error and warning messages), and 'all'(print error, warning and other informational messages).

-a, --assign=ASSIGN

The ASSIGNargument to the '--assign'command line option is of the form:

{DISPLAY}/{attribute name}[{display devices}]={value}

This assigns the attribute {attribute name} to the value {value} on the X Display {DISPLAY}. {DISPLAY} follows the usual {host}:{display}.{screen} syntax of the DISPLAY environment variable and is optional; when it is not specified, then it is implied following the same rule as the --ctrl-displayoption. If the X screen is not specified, then the assignment is made to all X screens. Note that the '/' is only required when {DISPLAY} is present.

{DISPLAY} can additionally include a target specification to direct an assignment to something other than an X screen. A target specification is contained within brackets and consists of a target type name, a colon, and the target id. The target type name can be one of screen, gpu, framelock, vcs, gvi,or fan;the target id is the index into the list of targets (for that target type). The target specification can be used in {DISPLAY} wherever an X screen can be used, following the syntax {host}:{display}[{target_type}:{target_id}]. See the output of

nvidia-settings -q all

for information on which target types can be used with which attributes. See the output of

nvidia-settings -q screens -q gpus -q framelocks -q vcs -q gvis -q fans

for lists of targets for each target type.

The [{display devices}] portion is also optional; if it is not specified, then the attribute is assigned to all display devices.

Some examples:

  -a FSAA=5
  -a localhost:0.0/DigitalVibrance[CRT-0]=0
  --assign="SyncToVBlank=1"
  -a [gpu:0]/DigitalVibrance[DFP-1]=63

-q, --query=QUERY

The QUERYargument to the '--query'command line option is of the form:

{DISPLAY}/{attribute name}[{display devices}]

This queries the current value of the attribute {attribute name} on the X Display {DISPLAY}. The syntax is the same as that for the '--assign'option, without '={value}'; specify '-q screens', '-q gpus', '-q framelocks', '-q vcs', '-q gvis', or '-q fans'to query a list of X screens, GPUs, Frame Lock devices, Visual Computing Systems, SDI Input Devices, or Fans, respectively, that are present on the X Display {DISPLAY}. Specify '-q all'to query all attributes.

-t, --terse

When querying attribute values with the '--query' command line option, only print the current value, rather than the more verbose description of the attribute, its valid values, and its current value.

-d, --display-device-string

When printing attribute values in response to the '--query' option, if the attribute value is a display device mask, print the value as a list of display devices (e.g., "CRT-0, DFP-0"), rather than a hexadecimal bit mask (e.g., 0x00010001).

-g, --glxinfo

Print GLX Information for the X display and exit.

-e, --describe=DESCRIBE

Prints information about a particular attribute. Specify 'all' to list the descriptions of all attributes. Specify 'list' to list the attribute names without a descriptions.

-p, --page=PAGE

The PAGEargument to the '--page'commandline option selects a particular page in the nvidia-settings user interface to display upon starting nvidia-settings. Valid values are the page names in the tree view on the left side of the nvidia-settings user interface; e.g.,

--page="X Screen 0"

Because some page names are not unique (e.g., a "PowerMizer" page is present under each GPU), the page name can optionally be prepended with the name of the parent X Screen or GPU page, followed by a comma. E.g.,

--page="GPU 0 - (Quadro 6000), PowerMizer"

The first page with a name matching the PAGEargument will be used. By default, the "X Server Information" page is displayed.

USER GUIDE

1.     Layout of the nvidia-settings GUI

2.     How OpenGL Interacts with nvidia-settings

3.     Loading Settings Automatically

4.     Command Line Interface

5.     X Display Names in the Config File

6.     Connecting to Remote X Servers

7.     Licensing

8.     TODO

1. Layout of the nvidia-settings GUI

Thenvidia-settingsGUI is organized with a list of different categories on the left side.Only one entry in the list can be selected at once, and the selected category controls which "page" is displayed on the right side of thenvidia-settingsGUI.

The category list is organized in a tree: each X screen contains the relevant subcategories beneath it.Similarly, the Display Devices category for a screen contains all the enabled display devices beneath it.Besides each X screen, the other top level category is "nvidia-settings Configuration", which configures behavior of thenvidia-settingsapplication itself.

Along the bottom of thenvidia-settingsGUI, from left to right, is:

1): a status bar which indicates the most recently altered option;
2): a Help button that toggles the display of a help window which provides a detailed explanation of the available options in the current page; and
3): a Quit button to exitnvidia-settings.

Most options throughoutnvidia-settingsare applied immediately.Notable exceptions are OpenGL options which are only read by OpenGL when an OpenGL application starts.

Details about the options on each page ofnvidia-settingsare available in the help window.

2. How OpenGL Interacts with nvidia-settings

When an OpenGL application starts, it downloads the current values from the X driver, and then reads the environment (seeAPPENDIX E: OPENGL ENVIRONMENT VARIABLE SETTINGSin the README).Settings from the X server override OpenGL's default values, and settings from the environment override values from the X server.

For example, by default OpenGL uses the FSAA setting requested by the application (normally, applications do not request any FSAA).An FSAA setting specified innvidia-settingswould override the OpenGL application's request.Similarly, the__GL_FSAA_MODEenvironment variable will override the application's FSAA setting, as well as any FSAA setting specified innvidia-settings.

Note that an OpenGL application only retrieves settings from the X server whenit starts, so if you make a change to an OpenGL value innvidia-settings,it will only apply to OpenGL applications which are started after that point in time.

3. Loading Settings Automatically

The NVIDIA X driver does not preserve values set withnvidia-settingsbetween runs of the X server (or even between logging in and logging out of X, withxdm(1),gdm,orkdm).This is intentional, because different users may have different preferences, thus these settings are stored on a per-user basis in a configuration file stored in the user's home directory.

The configuration file is named~/.nvidia-settings-rc.You can specify a different configuration file name with the--configcommand line option.

After you have runnvidia-settingsonce and have generated a configuration file, you can then run:

nvidia-settings --load-config-only

at any time in the future to upload these settings to the X server again.For example, you might place the above command in your~/.xinitrcfile so that your settings are applied automatically when you log in to X.

Your.xinitrcfile, which controls what X applications should be started when you log into X (or startx), might look something like this:

     nvidia-settings --load-config-only &     xterm &     evilwm

or:

     nvidia-settings --load-config-only &     gnome-session

If you do not already have an~/.xinitrcfile, then chances are thatxinit(1)is using a system-wide xinitrc file.This system wide file is typically here:

     /etc/X11/xinit/xinitrc

To use it, but also havenvidia-settingsupload your settings, you could create an~/.xinitrcwith the contents:

     nvidia-settings --load-config-only &     . /etc/X11/xinit/xinitrc

System administrators may choose to place thenvidia-settingsload command directly in the system xinitrc script.

Please see thexinit(1)man page for further details of configuring your~/.xinitrcfile.

4. Command Line Interface

nvidia-settingshas a rich command line interface: all attributes that can be manipulated with the GUI can also be queried and set from the command line.The command line syntax for querying and assigning attributes matches that of the.nvidia-settings-rcconfiguration file.

The--queryoption can be used to query the current value of attributes.This will also report the valid values for the attribute.You can runnvidia-settings --query allfor a complete list of available attributes, what the current value is, what values are valid for the attribute, and through which target types (e.g., X screens, GPUs) the attributes can be addressed.Additionally, individual attributes may be specified like this:

        nvidia-settings --query CursorShadow

Attributes that may differ per display device (for example, DigitalVibrance can be set independently on each display device when in TwinView) can be appended with a "display device name" within brackets; e.g.:

        nvidia-settings --query DigitalVibrance[CRT-0]

If an attribute is display device specific, but the query does not specify a display device, then the attribute value for all display devices will be queried.

An attribute name may be prepended with an X Display name and a forward slashto indicate a different X Display; e.g.:

        nvidia-settings --query localhost:0.0/DigitalVibrance[DFP-1]

An attribute name may also just be prepended with the screen number and a forward slash:

        nvidia-settings --query 0/DigitalVibrance[DFP-1]

in which case the default X Display will be used, but you can indicate to which X screen to direct the query (if your X server has multiple X screens).If no X screen is specified, then the attribute value will be queried for all X screens.

Attributes can be addressed through "target types".A target type indicates the object that is queried when you query an attribute.The default target type is an X screen, but other possible target types are GPUs, Frame Lock devices, Visual Computing Systems, SDI Input Devices, and fans.

Target types give you different granularities with which to perform queries and assignments.Since X screens can span multiple GPUs (in the case of Xinerama, or SLI), and multiple X screens can exist on the same GPU, it is sometimes useful to address attributes by GPU rather than X screen.

A target specification is contained within brackets and consists of a target type name, a colon, and the target id.The target type name can be one ofscreen,gpu,framelock,vcs,gvi,orfan;the target id is the index into the list of targets (for that target type).Target specifications can be used wherever an X screen is used in query and assignment commands; the target specification can be used either by itself on the left side of the forward slash, or as part of an X Display name.

For example, the following queries address X screen 0 on the localhost:

        nvidia-settings --query 0/VideoRam        nvidia-settings --query localhost:0.0/VideoRam        nvidia-settings --query [screen:0]/VideoRam        nvidia-settings --query localhost:0[screen:0]/VideoRam

To address GPU 0 instead, you can use either of:

        nvidia-settings --query [gpu:0]/VideoRam        nvidia-settings --query localhost:0[gpu:0]/VideoRam

See the output of

        nvidia-settings --query all

for what targets types can be used with each attribute.See the output of

        nvidia-settings --query screens --query gpus --query framelocks --query vcs --query gvis --query fans

for lists of targets for each target type.

The--assignoption can be used to assign a new value to an attribute.The valid values for an attribute are reported when the attribute is queried.The syntax for--assignis the same as--query,with the additional requirement that assignments also have an equal sign and the new value.For example:

        nvidia-settings --assign FSAA=2        nvidia-settings --assign 0/DigitalVibrance[CRT-1]=9        nvidia-settings --assign [gpu:0]/DigitalVibrance=0

Multiple queries and assignments may be specified on the command line for a single invocation ofnvidia-settings.

If either the--queryor--assignoptions are passed tonvidia-settings,the GUI will not be presented, andnvidia-settingswill exit after processing the assignments and/or queries.In this case, settings contained within the~/.nvidia-settings-rcconfiguration file will not be automatically uploaded to the X server, nor will the~/.nvidia-settings-rcconfiguration file be automatically updated to reflect attribute assignments made via the--assignoption.

5. X Display Names in the Config File

In the Command Line Interface section above, it was noted that you canspecify an attribute without any X Display qualifiers, with only an Xscreen qualifier, or with a full X Display name.For example:

        nvidia-settings --query FSAA        nvidia-settings --query 0/FSAA        nvidia-settings --query stravinsky.nvidia.com:0/FSAA

In the first two cases, the default X Display will be used, in the second case, the screen from the default X Display can be overridden, and in the third case, the entire default X Display can be overridden.

The same possibilities are available in the~/.nvidia-settings-rcconfiguration file.

For example, in a computer lab environment, you might log into any of multipleworkstations, and your home directory is NFS mounted to each workstation.In such a situation, you might want your~/.nvidia-settings-rcfile to be applicable to all the workstations.Therefore, you would not want your config file to qualify each attribute with an X Display Name.Leave the "Include X Display Names in the Config File" option unchecked on thenvidia-settingsConfiguration page (this is the default).

There may be cases when you do want attributes in the config file to be qualified with the X Display name.If you know what you are doing and want config file attributes to be qualified with an X Display, check the "Include X Display Names in the Config File" option on thenvidia-settingsConfiguration page.

In the typical home user environment where your home directory is local to one computer and you are only configuring one X Display, then it does not matter whether each attribute setting is qualified with an X Display Name.

6. Connecting to Remote X Servers

nvidia-settingsis an X client, but uses two separate X connections: one to display the GUI, and another to communicate the NV-CONTROL requests.These two X connections do not need to be to the same X server.For example, you might runnvidia-settingson the computer stravinsky.nvidia.com, export the display to the computer bartok.nvidia.com, but be configuring the X server on the computer schoenberg.nvidia.com:

        nvidia-settings --display=bartok.nvidia.com:0 \            --ctrl-display=schoenberg.nvidia.com:0

If--ctrl-displayis not specified, then the X Display to control is what--displayindicates.If--displayis also not specified, then the$DISPLAYenvironment variable is used.

Note, however, that you will need to have X permissions configured such that you can establish an X connection from the computer on which you are runningnvidia-settings(stravinsky.nvidia.com) to the computer where you are displaying the GUI (bartok.nvidia.com) and the computer whose X Display you are configuring (schoenberg.nvidia.com).

The simplest, most common, and least secure mechanism to do this is to use 'xhost' to allow access from the computer on which you are runningnvidia-settings.

        (issued from bartok.nvidia.com)        xhost +stravinsky.nvidia.com        (issued from schoenberg.nvidia.com)        xhost +stravinsky.nvidia.com

This will allow all X clients run on stravinsky.nvidia.com to connect and display on bartok.nvidia.com's X server and configure schoenberg.nvidia.com's X server.

Please see thexauth(1)andxhost(1)man pages, or refer to your system documentation on remote X applications and security.You might also Google for terms such as "remote X security" or "remote X Windows", and see documents such as the Remote X Apps mini-HOWTO:

< http://www.tldp.org/HOWTO/Remote-X-Apps.html >

Please also note that the remote X server to be controlled must be using the NVIDIA X driver.

7. Licensing

The source code tonvidia-settingsis released as GPL.The most recent official version of the source code is available here:

< ftp://download.nvidia.com/XFree86/nvidia-settings/ >

Note thatnvidia-settingsis simply an NV-CONTROL client.It uses the NV-CONTROL X extension to communicate with the NVIDIA X server to query current settings and make changes to settings.

You can make additions directly tonvidia-settings,or write your own NV-CONTROL client, usingnvidia-settingsas an example.

Documentation on the NV-CONTROL extension and additional sample clients are available in thenvidia-settingssource tarball.Patches can be submitted to linux-bugsAATTnvidia.com.

8. TODO

There are many things still to be added tonvidia-settings,some of which include:

-: different toolkits?The GUI fornvidia-settingsis cleanly abstracted from the back-end ofnvidia-settingsthat parses the configuration file and command line, communicates with the X server, etc.If someone were so inclined, a different front-end GUI could be implemented.
-: write a design document explaining hownvidia-settingsis designed; presumably this would make it easier for people to become familiar with the code base.

If there are other things you would like to see added (or better yet, would like to add yourself), please contact linux-bugsAATTnvidia.com.

FILES

~/.nvidia-settings-rc

EXAMPLES

nvidia-settings: Starts thenvidia-settingsgraphical interface.
nvidia-settings --load-config-only: Loads the settings stored in~/.nvidia-settings-rcand exits.
nvidia-settings --rewrite-config-file: Writes the current X server configuration to~/.nvidia-settings-rcfile and exits.
nvidia-settings --query FSAA: Query the value of the full-screen antialiasing setting.
nvidia-settings --assign RedGamma=2.0 --assign BlueGamma=2.0 --assign GreenGamma=2.0: Set the gamma of the screen to 2.0.