nvidia-settings (1) - Linux Manuals
nvidia-settings: configure the NVIDIA graphics driver
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={none | errors | deprecations | warnings | all}]
[--describe={all | list | attribute_name}]
attr
has the form:
Values such as brightness and gamma, XVideo attributes, temperature, and OpenGL settings can be queried and configured via
nvidia-settings.
When
nvidia-settings
starts, 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.
When
nvidia-settings
exits, it queries the current settings from the X server and saves them to the configuration file.
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-display
option. 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, fan, thermalsensor, svp,
or
dpy;
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
for information on which target types can be used with which attributes. See the output of
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:
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 fans'
, '-q thermalsensors', '-q svps', or '-q dpys' to query a list of X screens, GPUs, Frame Lock devices, Visual Computing Systems, Devices, Fans, Thermal Sensors, 3D Vision Pro Transceivers, or Display Devices, respectively, that are present on the X Display {DISPLAY}. Specify
'-q all'
to query all attributes.
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.,
The first page with a name matching the
PAGE
argument will be used. By default, the "System Information" page is displayed.
The '--list-targets-only' option will cause nvidia-settings to list the targets on which the query/assign operation would have been performed, without actually performing the operation(s), and exit.
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 the
nvidia-settings
application itself.
Along the bottom of the
nvidia-settings
GUI, from left to right, is:
Most options throughout
nvidia-settings
are 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 of
nvidia-settings
are available in the help window.
When an OpenGL application starts, it downloads the current values from the X driver, and then reads the environment (see
APPENDIX E: OPENGL ENVIRONMENT VARIABLE SETTINGS
in 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 in
nvidia-settings
would override the OpenGL application's request.
Similarly, the
__GL_FSAA_MODE
environment variable will override the application's FSAA setting, as well as any FSAA setting specified in
nvidia-settings.
Note that an OpenGL application only retrieves settings from the X server when
it starts, so if you make a change to an OpenGL value in
nvidia-settings,
it will only apply to OpenGL applications which are started after that point in time.
The configuration file is named
~/.nvidia-settings-rc.
You can specify a different configuration file name with the
--config
command line option.
After you have run
nvidia-settings
once and have generated a configuration file, you can then run:
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
~/.xinitrc
file so that your settings are applied automatically when you log in to X.
Your
.xinitrc
file, which controls what X applications should be started when you log into X (or startx), might look something like this:
Please see the
xinit(1)
man page for further details of configuring your
~/.xinitrc
file.
The
--query
option can be used to query the current value of attributes.
This will also report the valid values for the attribute.
You can run
nvidia-settings --query all
for 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:
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, fans, thermal sensors, 3D Vision Pro Transceivers and display devices.
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 may consist of a target type name, a colon, and the target id.
The target type name can be one of
screen,
gpu,
framelock,
fan,
thermalsensor,
svp,
or
dpy;
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:
A target name may be used instead of a target id, in which case all targets with matching names are processed.
For example, querying the DigitalVibrance of display device DVI-I-1 may be done like so:
For example, querying the BusRate of all GPUs may be done like so:
The target specification may also include a target qualifier.
This is useful to limit processing to a subset of targets, based on an existing relationship(s) to other targets.
The target qualifier is specified by prepending a target type name, a colon, the target id, and a period to the existing specification.
Only one qualitfer may be specified.
For example, querying the RefreshRate of all DFP devices on GPU 1 may be done like so:
See the output of
To enable support for the "GPUGraphicsClockOffset" and "GPUMemoryTransferRateOffset" attributes, ensure that the "Coolbits" X configuration option includes the value "8" in the bitmask.
For more details, refer to the documentation of the "Coolbits" option in the NVIDIA driver README.
Query the "GPUPerfModes" string attribute to see a list of the available performance modes:
Each performance mode is presented as a comma-separated list of "token=value" pairs.
Each set of performance mode tokens is separated by a ";".
The "perf" token indicates the performance level.
The "*editable" tokens indicate which domains within the performance level can have an offset applied.
The "GPUGraphicsClockOffset" and "GPUMemoryTransferRateOffset" attributes map respectively to the "nvclock" and "memtransferrate" tokens of performance levels in the "GPUPerfModes" string.
Note that the clock manipulation attributes "GPUGraphicsClockOffset" and "GPUMemoryTransferRateOffset" apply to the offsets of specific performance levels.
The performance level is specified in square brackets after the attribute name.
For example, to query the "GPUGraphicsClockOffset" for performance level 2:
Multiple queries and assignments may be specified on the command line for a single invocation of
nvidia-settings.
Assignments are processed in the order they are entered on the command line.
If multiple assignments are made to the same attribute or to multiple attributes with dependencies, then the later assignments will have priority.
If either the
--query
or
--assign
options are passed to
nvidia-settings,
the GUI will not be presented, and
nvidia-settings
will exit after processing the assignments and/or queries.
In this case, settings contained within the
~/.nvidia-settings-rc
configuration file will not be automatically uploaded to the X server, nor will the
~/.nvidia-settings-rc
configuration file be automatically updated to reflect attribute assignments made via the
--assign
option.
The same possibilities are available in the
~/.nvidia-settings-rc
configuration file.
For example, in a computer lab environment, you might log into any of multiple
workstations, and your home directory is NFS mounted to each workstation.
In such a situation, you might want your
~/.nvidia-settings-rc
file 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 the
nvidia-settings
Configuration 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 the
nvidia-settings
Configuration 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.
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 running
nvidia-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 running
nvidia-settings.
Please see the
xauth(1)
and
xhost(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:
Please also note that the remote X server to be controlled must be using the NVIDIA X driver.
Note that
nvidia-settings
is 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 to
nvidia-settings,
or write your own NV-CONTROL client, using
nvidia-settings
as an example.
Documentation on the NV-CONTROL extension and additional sample clients are available in the
nvidia-settings
source tarball.
Patches can be submitted to linux-bugs [at] nvidia.com.
If there are other things you would like to see added (or better yet, would like to add yourself), please contact linux-bugs [at] nvidia.com.
DESCRIPTION
The
nvidia-settings
utility 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.
OPTIONS
USER GUIDE
Contents
1.
2.
3.
4.
5.
6.
7.
8.
1. Layout of the nvidia-settings GUI
The
nvidia-settings
GUI 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 the
nvidia-settings
GUI.
2. How OpenGL Interacts with nvidia-settings
3. Loading Settings Automatically
The NVIDIA X driver does not preserve values set with
nvidia-settings
between runs of the X server (or even between logging in and logging out of X, with
xdm(1),
gdm,
or
kdm
).
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.
nvidia-settings --load-config-only &
xterm &
evilwm
or:
nvidia-settings --load-config-only &
gnome-session
If you do not already have an
~/.xinitrc
file, then chances are that
xinit(1)
is using a system-wide xinitrc file.
This system wide file is typically here:
/etc/X11/xinit/xinitrc
To use it, but also have
nvidia-settings
upload your settings, you could create an
~/.xinitrc
with the contents:
nvidia-settings --load-config-only &
. /etc/X11/xinit/xinitrc
System administrators may choose to place the
nvidia-settings
load command directly in the system xinitrc script.
4. Command Line Interface
nvidia-settings
has 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-rc
configuration file.
nvidia-settings --query Overlay
An attribute name may be prepended with an X Display name and a forward slash to indicate a different X Display; e.g.:
nvidia-settings --query localhost:0.0/Overlay
An attribute name may also just be prepended with the screen number and a forward slash:
nvidia-settings --query 0/Overlay
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 valid targets of the attribute (eg GPUs, Displays X screens, etc).
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
Note that if a target specification is present, it will override any X screen specified in the display name as the target to process.
For example, the following query would address GPU 0, and not X screen 1:
nvidia-settings --query localhost:0.1[gpu:0]/VideoRam
nvidia-settings --query [dpy:DVI-I-1]/DigitalVibrance
When a target name is specified, the target type name may be omitted, though this should be used with caution since the name will be matched across all target types.
The above example could be written as:
nvidia-settings --query [DVI-I-1]/DigitalVibrance
The target name may also simply be a target type name, in which case all targets of that type will be queried.
nvidia-settings --query [gpu]/BusRate
nvidia-settings --query [GPU:1.DPY:DFP]/RefreshRate
Likewise, a simple target name (or target type name) may be used as the qualifier.
For example, to query the BusType of all GPUs that have DFPs can be done like so:
nvidia-settings --query [DFP.GPU]/BusType
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 fans --query thermalsensors --query svps --query dpys
for lists of targets for each target type.
nvidia-settings --query GPUPerfModes
nvidia-settings --query GPUGraphicsClockOffset[2]
The
--assign
option 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
--assign
is 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 [CRT-1]/DigitalVibrance=9
nvidia-settings --assign [gpu:0]/DigitalVibrance=0
nvidia-settings --assign [gpu:0]/GPUGraphicsClockOffset[2]=10
5. X Display Names in the Config File
In the Command Line Interface section above, it was noted that you can
specify an attribute without any X Display qualifiers, with only an X
screen 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.
6. Connecting to Remote X Servers
nvidia-settings
is 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 run
nvidia-settings
on 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-display
is not specified, then the X Display to control is what
--display
indicates.
If
--display
is also not specified, then the
$DISPLAY
environment variable is used.
(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.
7. Licensing
The source code to
nvidia-settings
is released as GPL.
The most recent official version of the source code is available here:
8. TODO
There are many things still to be added to
nvidia-settings,
some of which include:
FILES
EXAMPLES
AUTHOR
Aaron Plattner
NVIDIA Corporation
COPYRIGHT
Copyright © 2010 NVIDIA Corporation.