1 .\" Copyright (C) 2006 NVIDIA Corporation.
2 .\" WARNING: THIS FILE IS AUTO-GENERATED! Edit doc/nvidia-settings.1.m4 instead.
3 .\" Define the .URL macro and then override it with the www.tmac package if it
6 \\$2 \(la \\$1 \(ra\\$3
8 .if \n[.g] .mso www.tmac
9 .TH nvidia\-settings 1 2006-03-17 "nvidia\-settings 1.0"
11 nvidia\-settings \- configure the NVIDIA graphics driver
13 .BI "nvidia\-settings [" "options" "]"
15 .BI "nvidia\-settings [" "options" "] \-\-no\-config"
17 .BI "nvidia\-settings [" "options" "] \-\-load\-config\-only"
19 .BI "nvidia\-settings [" "options" "] {\-\-query=" attr " | \-\-assign=" attr = value "} ..."
21 .BI "nvidia\-settings [" "options" "] \-\-glxinfo"
24 .BI "[-vh] [\-\-config=" configfile "] [\-c " ctrl-display "]"
26 .I " \fB[\-\-verbose=\fP{\fIerrors \fP|\fI warnings \fP|\fI all\fP}\fB]"
28 .I " \fB[\-\-describe=\fP{\fIall \fP|\fI list \fP|\fI attribute_name\fP}\fB]"
33 .IB DISPLAY / attribute_name [ display_devices ]
37 utility is a tool for configuring the NVIDIA graphics driver.
38 It operates by communicating with the NVIDIA X driver, querying and updating state as appropriate.
39 This communication is done with the NV-CONTROL X extension.
41 Values such as brightness and gamma, XVideo attributes, temperature, and OpenGL settings can be queried and configured via
46 starts, it reads the current settings from its configuration file and sends those settings to the X server.
47 Then, it displays a graphical user interface (GUI) for configuring the current settings.
50 exits, it queries the current settings from the X server and saves them to the configuration file.
59 Print usage information and exit.
61 .BI "\-\-config=" config
62 Use the configuration file
64 rather than the default
65 .I ~/.nvidia\-settings\-rc
67 .BI "\-c, \-\-ctrl\-display=" ctrl-display
68 Control the specified X display.
69 If this option is not given, then
71 will control the display specifed by
73 If that is not given, then the
75 environment variable is used.
77 .B \-n, \-\-no\-config
78 Do not load the configuration file.
79 This mode of operation is useful if
81 has difficulties starting due to problems with applying settings in the configuration file.
83 .B \-l, \-\-load\-config\-only
84 Load the configuration file, send the values specified therein to the X server, and exit.
85 This mode of operation is useful to place in your .xinitrc file, for example.
87 .B \-r, \-\-rewrite\-config\-file
88 Write the current X server configuration to the configuration file, and exit without starting
89 a grpahical user interface.See Examples section.
91 .BI "\-V, \-\-verbose=" verbosity
92 Controls how much information is printed.
93 By default, the verbosity is
95 and only error messages are printed.
99 can be one of the following values:
105 - Print errors and warnings.
108 - Print errors, warnings, and other information.
110 .BI "\-a, \-\-assign=" assign
115 commandline option is of the form:
118 {DISPLAY}/{attribute name}[{display devices}]={value}
121 This assigns the attribute {attribute name} to the value {value} on the X Display {DISPLAY}.
122 {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
125 If the X screen is not specified, then the assignment is made to all X screens.
126 Note that the '/' is only required when {DISPLAY} is present.
129 {DISPLAY} can additionally include a target specification to direct an assignment to something other than an X screen.
130 A target specification is contained within brackets and consists of a target type name, a colon, and the target id.
131 The target type name can be one of
136 the target id is the index into the list of targets (for that target type).
137 The target specification can be used in {DISPLAY} wherever an X screen can be used, following the syntax {host}:{display}[{target_type}:{target_id}].
141 nvidia-settings --query all
144 for information on which target types can be used with which attributes.
148 nvidia-settings -q screens -q gpus -q framelocks
151 for lists of targets for each target type.
154 The [{display devices}] portion is also optional; if it is not specified, then the attribute is assigned to all display devices.
161 -a localhost:0.0/DigitalVibrance[CRT-0]=0
162 --assign="SyncToVBlank=1"
163 -a [gpu:0]/DigitalVibrance[DFP-1]=63
167 .BI "\-q, \-\-query=" query
172 commandline option is of the form:
175 {DISPLAY}/{attribute name}[{display devices}]
178 This queries the current value of the attribute {attribute name} on the X Display {DISPLAY}.
179 The syntax is the same as that for the
188 to query a list of X screens, GPUs, or Frame Lock devices, respectively, that are present on the X Display {DISPLAY}.
191 to query all attributes.
194 Print GLX Information for the X display and exit.
197 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.
200 1. Layout of the nvidia\-settings GUI
202 2. How OpenGL Interacts with nvidia\-settings
204 3. Loading Settings Automatically
206 4. Commandline Interface
208 5. X Display Names in the Config File
210 6. Connecting to Remote X Servers
216 .SS 1. Layout of the nvidia\-settings GUI
219 GUI is organized with a list of different categories on the left side.
220 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
224 The category list is organized in a tree: each X screen contains the relevant subcategories beneath it.
225 Similarly, the Display Devices category for a screen contains all the enabled display devices beneath it.
226 Besides each X screen, the other top level category is "nvidia\-settings Configuration", which configures behavior of the
230 Along the bottom of the
232 GUI, from left to right, is:
235 a status bar which indicates the most recently altered option;
238 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
241 a Quit button to exit
244 Most options throughout
246 are applied immediately.
247 Notable exceptions are OpenGL options which are only read by OpenGL when an OpenGL application starts.
249 Details about the options on each page of
251 are available in the help window.
252 .SS 2. How OpenGL Interacts with nvidia\-settings
254 When an OpenGL application starts, it downloads the current values from the X driver, and then reads the environment (see
255 .I APPENDIX E: OPENGL ENVIRONMENT VARIABLE SETTINGS
257 Settings from the X server override OpenGL's default values, and settings from the environment override values from the X server.
259 For example, by default OpenGL uses the FSAA setting requested by the application (normally, applications do not request any FSAA).
260 An FSAA setting specified in
262 would override the OpenGL application's request.
265 environment variable will override the application's FSAA setting, as well as any FSAA setting specified in
268 Note that an OpenGL application only retrieves settings from the X server when
269 it starts, so if you make a change to an OpenGL value in
271 it will only apply to OpenGL applications which are started after that point in time.
272 .SS 3. Loading Settings Automatically
273 The NVIDIA X driver does not preserve values set with
275 between runs of the X server (or even between logging in and logging out of X, with
281 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.
283 The configuration file is named
284 .IR ~/.nvidia\-settings\-rc .
285 You can specify a different configuration file name with the
291 once and have generated a configuration file, you can then run:
294 nvidia\-settings \-\-load\-config\-only
296 at any time in the future to upload these settings to the X server again.
297 For example, you might place the above command in your
299 file so that your settings are applied automatically when you log in to X.
303 file, which controls what X applications should be started when you log into X (or startx), might look something like this:
306 nvidia-settings --load-config-only &
314 nvidia-settings --load-config-only &
318 If you do not already have an
320 file, then chances are that
322 is using a system-wide xinitrc file.
323 This system wide file is typically here:
326 /etc/X11/xinit/xinitrc
329 To use it, but also have
331 upload your settings, you could create an
336 nvidia-settings --load-config-only &
337 . /etc/X11/xinit/xinitrc
340 System administrators may choose to place the
342 load command directly in the system xinitrc script.
346 man page for further details of configuring your
349 .SS 4. Commandline Interface
351 has a rich commandline interface: all attributes that can be manipulated with the GUI can also be queried and set from the command line.
352 The commandline syntax for querying and assigning attributes matches that of the
353 .I .nvidia\-settings\-rc
358 option can be used to query the current value of attributes.
359 This will also report the valid values for the attribute.
361 .B nvidia\-settings \-\-query all
362 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.
363 Additionally, individual attributes may be specified like this:
366 nvidia-settings --query CursorShadow
369 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.:
372 nvidia-settings --query DigitalVibrance[CRT-0]
375 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.
377 An attribute name may be prepended with an X Display name and a forward slash
378 to indicate a different X Display; e.g.:
381 nvidia-settings --query localhost:0.0/DigitalVibrance[DFP-1]
384 An attribute name may also just be prepended with the screen number and a forward slash:
387 nvidia-settings --query 0/DigitalVibrance[DFP-1]
390 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).
391 If no X screen is specified, then the attribute value will be queried for all X screens.
393 Attributes can be addressed through "target types".
394 A target type indicates the object that is queried when you query an attribute.
395 The default target type is an X screen, but other possible target types are GPUs and Frame Lock devices.
397 Target types give you different granularities with which to perform queries and assignments.
398 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.
400 A target specification is contained within brackets and consists of a target type name, a colon, and the target id.
401 The target type name can be one of
406 the target id is the index into the list of targets (for that target type).
407 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.
409 For example, the following queries address X screen 0 on the localhost:
412 nvidia-settings --query 0/VideoRam
413 nvidia-settings --query localhost:0.0/VideoRam
414 nvidia-settings --query [screen:0]/VideoRam
415 nvidia-settings --query localhost:0[screen:0]/VideoRam
418 To address GPU 0 instead, you can use either of:
421 nvidia-settings --query [gpu:0]/VideoRam
422 nvidia-settings --query localhost:0[gpu:0]/VideoRam
428 nvidia-settings --query all
431 for what targets types can be used with each attribute.
435 nvidia-settings --query screens --query gpus --query framelocks
438 for lists of targets for each target type.
442 option can be used to assign a new value to an attribute.
443 The valid values for an attribute are reported when the attribute is queried.
448 with the additional requirement that assignments also have an equal sign and the new value.
452 nvidia-settings --assign FSAA=2
453 nvidia-settings --assign 0/DigitalVibrance[CRT-1]=9
454 nvidia-settings --assign [gpu:0]/DigitalVibrance=0
457 Multiple queries and assignments may be specified on the commandline for a single invocation of
464 options are passed to
466 the GUI will not be presented, and
468 will exit after processing the assignments and/or queries.
469 .SS 5. X Display Names in the Config File
470 In the Commandline 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.
474 nvidia-settings --query FSAA
475 nvidia-settings --query 0/FSAA
476 nvidia-settings --query stravinsky.nvidia.com:0/FSAA
479 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.
481 The same possibilities are available in the
482 .I ~/.nvidia\-settings-rc
485 For example, in a computer lab environment, you might log into any of multiple
486 workstations, and your home directory is NFS mounted to each workstation.
487 In such a situation, you might want your
488 .I ~/.nvidia\-settings-rc
489 file to be applicable to all the workstations.
490 Therefore, you would not want your config file to qualify each attribute with an X Display Name.
491 Leave the "Include X Display Names in the Config File" option unchecked on the
493 Configuration page (this is the default).
495 There may be cases when you do want attributes in the config file to be qualified with the X Display name.
496 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
500 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.
501 .SS 6. Connecting to Remote X Servers
503 is an X client, but uses two separate X connections: one to display the GUI, and another to communicate the NV-CONTROL requests.
504 These two X connections do not need to be to the same X server.
505 For example, you might run
507 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:
510 nvidia-settings --display=bartok.nvidia.com:0 \\
511 --ctrl-display=schoenberg.nvidia.com:0
516 is not specified, then the X Display to control is what
521 is also not specified, then the
523 environment variable is used.
525 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
527 (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).
529 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
533 (issued from bartok.nvidia.com)
534 xhost +stravinsky.nvidia.com
536 (issued from schoenberg.nvidia.com)
537 xhost +stravinsky.nvidia.com
540 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.
546 man pages, or refer to your system documentation on remote X applications and security.
547 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:
550 .URL http://www.tldp.org/HOWTO/Remote-X-Apps.html
552 Please also note that the remote X server to be controlled must be using the NVIDIA X driver.
557 The most recent official version of the source code is available here:
560 .URL ftp://download.nvidia.com/XFree86/nvidia-settings/
564 is simply an NV-CONTROL client.
565 It uses the NV-CONTROL X extension to communicate with the NVIDIA X server to query current settings and make changes to settings.
567 You can make additions directly to
569 or write your own NV-CONTROL client, using
573 Documentation on the NV-CONTROL extension and additional sample clients are available in the
576 Patches can be submitted to linux-bugs@nvidia.com.
578 There are many things still to be added to
580 some of which include:
586 is cleanly abstracted from the backend of
588 that parses the configuration file and commandline, communicates with the X server, etc.
589 If someone were so inclined, a different frontend GUI could be implemented.
592 write a design document explaining how
594 is architected; presumably this would make it easier for people to become familiar with the code base.
596 If there are other things you would like to see added (or better yet, would like to add yourself), please contact linux-bugs@nvidia.com.
599 .I ~/.nvidia\-settings\-rc
607 .B nvidia\-settings \-\-load\-config\-only
608 Loads the settings stored in
609 .I ~/.nvidia\-settings\-rc
612 .B nvidia\-settings \-\-rewrite\-config\-file
613 Writes the current X server configuration to
614 .I ~/.nvidia\-settings\-rc
617 .B nvidia\-settings \-\-query FSAA
618 Query the value of the full-screen antialiasing setting.
620 .B nvidia\-settings \-\-assign RedGamma=2.0 \-\-assign BlueGamma=2.0 \-\-assign GreenGamma=2.0
621 Set the gamma of the screen to 2.0.
627 .BR nvidia\-xconfig (1)
629 Copyright \(co 2006 NVIDIA Corporation.