import NVIDIA-FreeBSD-x86-190.42
[nvidia.git] / x11 / man / nvidia-settings.1
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
4 .\" exists.
5 .de URL
6 \\$2 \(la \\$1 \(ra\\$3
7 ..
8 .if \n[.g] .mso www.tmac
9 .TH nvidia\-settings 1 2006-03-17 "nvidia\-settings 1.0"
10 .SH NAME
11 nvidia\-settings \- configure the NVIDIA graphics driver
12 .SH SYNOPSIS
13 .BI "nvidia\-settings [" "options" "]"
14 .br
15 .BI "nvidia\-settings [" "options" "] \-\-no\-config"
16 .br
17 .BI "nvidia\-settings [" "options" "] \-\-load\-config\-only"
18 .br
19 .BI "nvidia\-settings [" "options" "] {\-\-query=" attr " | \-\-assign=" attr = value "} ..."
20 .br
21 .BI "nvidia\-settings [" "options" "] \-\-glxinfo"
22 .PP
23 Options:
24 .BI "[-vh] [\-\-config=" configfile "] [\-c " ctrl-display "]"
25 .br
26 .I "         \fB[\-\-verbose=\fP{\fIerrors \fP|\fI warnings \fP|\fI all\fP}\fB]"
27 .br
28 .I "         \fB[\-\-describe=\fP{\fIall \fP|\fI list \fP|\fI attribute_name\fP}\fB]"
29 .PP
30 .I attr
31 has the form:
32 .ti +5
33 .IB DISPLAY / attribute_name [ display_devices ]
34 .SH DESCRIPTION
35 The
36 .B nvidia\-settings
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.
40 .PP
41 Values such as brightness and gamma, XVideo attributes, temperature, and OpenGL settings can be queried and configured via
42 .B nvidia\-settings.
43 .PP
44 When
45 .B nvidia\-settings
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.
48 When
49 .B nvidia\-settings
50 exits, it queries the current settings from the X server and saves them to the configuration file.
51 .SH OPTIONS
52 .TP
53 .B \-v, \-\-version
54 Print the
55 .B nvidia\-settings
56 version and exit.
57 .TP
58 .B \-h, \-\-help
59 Print usage information and exit.
60 .TP
61 .BI "\-\-config=" config
62 Use the configuration file
63 .I config
64 rather than the default
65 .I ~/.nvidia\-settings\-rc
66 .TP
67 .BI "\-c, \-\-ctrl\-display=" ctrl-display
68 Control the specified X display.
69 If this option is not given, then
70 .B nvidia\-settings
71 will control the display specifed by
72 .B \-\-display.
73 If that is not given, then the
74 .I $DISPLAY
75 environment variable is used.
76 .TP
77 .B \-n, \-\-no\-config
78 Do not load the configuration file.
79 This mode of operation is useful if
80 .B nvidia\-settings
81 has difficulties starting due to problems with applying settings in the configuration file.
82 .TP
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.
86 .TP
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.
90 .TP
91 .BI "\-V, \-\-verbose=" verbosity
92 Controls how much information is printed.
93 By default, the verbosity is 
94 .B errors
95 and only error messages are printed.
96 .br
97
98 .I verbosity
99 can be one of the following values:
100 .ti +5
101 .B errors
102 - Print errors.
103 .ti +5
104 .B warnings
105 - Print errors and warnings.
106 .ti +5
107 .B all
108 - Print errors, warnings, and other information.
109 .TP
110 .BI "\-a, \-\-assign=" assign
111 The
112 .I assign
113 argument to the
114 .B \-\-assign
115 commandline option is of the form:
116 .nf
117
118         {DISPLAY}/{attribute name}[{display devices}]={value}
119
120 .fi
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
123 .B \-\-ctrl\-display
124 option.
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.
127 .sp
128 .br
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
132 .B screen,
133 .B gpu,
134 .B framelock,
135 .B vcs,
136 .B gvi,
137 or
138 .B fan;
139 the target id is the index into the list of targets (for that target type).
140 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 See the output of
142 .nf
143
144         nvidia-settings --query all
145
146 .fi
147 for information on which target types can be used with which attributes.
148 See the output of
149 .nf
150
151         nvidia-settings -q screens -q gpus -q framelocks -q vcs -q gvis -q fans
152
153 .fi
154 for lists of targets for each target type.
155 .br
156 .sp
157 The [{display devices}] portion is also optional; if it is not specified, then the attribute is assigned to all display devices.
158 .br
159 .sp
160 Some examples:
161 .nf
162
163         -a FSAA=5
164         -a localhost:0.0/DigitalVibrance[CRT-0]=0
165         --assign="SyncToVBlank=1"
166         -a [gpu:0]/DigitalVibrance[DFP-1]=63
167
168 .fi
169 .TP
170 .BI "\-q, \-\-query=" query
171 The
172 .I query
173 argument to the
174 .B \-\-query
175 commandline option is of the form:
176 .nf
177
178         {DISPLAY}/{attribute name}[{display devices}]
179
180 .fi
181 This queries the current value of the attribute {attribute name} on the X Display {DISPLAY}.
182 The syntax is the same as that for the
183 .B \-\-assign
184 option, without
185 .B ={value}.
186 Specify
187 .B \-q screens,
188 .B \-q gpus,
189 .B \-q framelocks,
190 .B \-q vcs,
191 .B \-q gvis,
192 or
193 .B \-q fans
194 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}.
195 Specify
196 .B \-q all
197 to query all attributes.
198 .TP
199 .B \-g, \-\-glxinfo
200 Print GLX Information for the X display and exit.
201 .TP
202 .B \-e, \-\-describe
203 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.
204 .SH "USER GUIDE"
205 .SS Contents
206 1.      Layout of the nvidia\-settings GUI
207 .br
208 2.      How OpenGL Interacts with nvidia\-settings
209 .br
210 3.      Loading Settings Automatically
211 .br
212 4.      Commandline Interface
213 .br
214 5.      X Display Names in the Config File
215 .br
216 6.      Connecting to Remote X Servers
217 .br
218 7.      Licensing
219 .br
220 8.      TODO
221 .br
222 .SS 1. Layout of the nvidia\-settings GUI
223 The
224 .B nvidia\-settings
225 GUI is organized with a list of different categories on the left side.
226 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
227 .B nvidia\-settings
228 GUI.
229 .PP
230 The category list is organized in a tree: each X screen contains the relevant subcategories beneath it.
231 Similarly, the Display Devices category for a screen contains all the enabled display devices beneath it.
232 Besides each X screen, the other top level category is "nvidia\-settings Configuration", which configures behavior of the
233 .B nvidia\-settings
234 application itself.
235 .PP
236 Along the bottom of the
237 .B nvidia\-settings
238 GUI, from left to right, is:
239 .TP
240 1)
241 a status bar which indicates the most recently altered option;
242 .TP
243 2)
244 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
245 .TP
246 3)
247 a Quit button to exit
248 .B nvidia\-settings.
249 .PP
250 Most options throughout
251 .B nvidia\-settings
252 are applied immediately.
253 Notable exceptions are OpenGL options which are only read by OpenGL when an OpenGL application starts.
254 .PP
255 Details about the options on each page of
256 .B nvidia\-settings
257 are available in the help window.
258 .SS 2. How OpenGL Interacts with nvidia\-settings
259 .PP
260 When an OpenGL application starts, it downloads the current values from the X driver, and then reads the environment (see
261 .I APPENDIX E: OPENGL ENVIRONMENT VARIABLE SETTINGS
262 in the README).
263 Settings from the X server override OpenGL's default values, and settings from the environment override values from the X server.
264 .PP
265 For example, by default OpenGL uses the FSAA setting requested by the application (normally, applications do not request any FSAA).
266 An FSAA setting specified in
267 .B nvidia\-settings
268 would override the OpenGL application's request.
269 Similarly, the
270 .B __GL_FSAA_MODE
271 environment variable will override the application's FSAA setting, as well as any FSAA setting specified in
272 .B nvidia\-settings.
273 .PP
274 Note that an OpenGL application only retrieves settings from the X server when
275 it starts, so if you make a change to an OpenGL value in
276 .B nvidia\-settings,
277 it will only apply to OpenGL applications which are started after that point in time.
278 .SS 3. Loading Settings Automatically
279 The NVIDIA X driver does not preserve values set with
280 .B nvidia\-settings
281 between runs of the X server (or even between logging in and logging out of X, with
282 .BR xdm (1),
283 .B gdm,
284 or
285 .B kdm
286 ).
287 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.
288 .PP
289 The configuration file is named
290 .IR ~/.nvidia\-settings\-rc .
291 You can specify a different configuration file name with the
292 .B \-\-config
293 commandline option.
294 .PP
295 After you have run
296 .B nvidia\-settings
297 once and have generated a configuration file, you can then run:
298 .sp
299 .ti +5
300 nvidia\-settings \-\-load\-config\-only
301 .sp
302 at any time in the future to upload these settings to the X server again.
303 For example, you might place the above command in your
304 .I ~/.xinitrc
305 file so that your settings are applied automatically when you log in to X.
306 .PP
307 Your
308 .I .xinitrc
309 file, which controls what X applications should be started when you log into X (or startx), might look something like this:
310 .nf
311
312      nvidia-settings --load-config-only &
313      xterm &
314      evilwm
315
316 .fi
317 or:
318 .nf
319
320      nvidia-settings --load-config-only &
321      gnome-session
322
323 .fi
324 If you do not already have an
325 .I ~/.xinitrc
326 file, then chances are that
327 .BR xinit (1)
328 is using a system-wide xinitrc file.
329 This system wide file is typically here:
330 .nf
331
332      /etc/X11/xinit/xinitrc
333
334 .fi
335 To use it, but also have
336 .B nvidia\-settings
337 upload your settings, you could create an
338 .I ~/.xinitrc
339 with the contents:
340 .nf
341
342      nvidia-settings --load-config-only &
343      . /etc/X11/xinit/xinitrc
344
345 .fi
346 System administrators may choose to place the
347 .B nvidia\-settings
348 load command directly in the system xinitrc script.
349 .PP
350 Please see the
351 .BR xinit (1)
352 man page for further details of configuring your
353 .I ~/.xinitrc
354 file.
355 .SS 4. Commandline Interface
356 .B nvidia\-settings
357 has a rich commandline interface: all attributes that can be manipulated with the GUI can also be queried and set from the command line.
358 The commandline syntax for querying and assigning attributes matches that of the 
359 .I .nvidia\-settings\-rc
360 configuration file.
361 .PP
362 The
363 .B \-\-query
364 option can be used to query the current value of attributes.
365 This will also report the valid values for the attribute.
366 You can run
367 .B nvidia\-settings \-\-query all
368 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.
369 Additionally, individual attributes may be specified like this:
370 .nf
371
372         nvidia-settings --query CursorShadow
373
374 .fi
375 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.:
376 .nf
377
378         nvidia-settings --query DigitalVibrance[CRT-0]
379
380 .fi
381 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.
382 .PP
383 An attribute name may be prepended with an X Display name and a forward slash
384 to indicate a different X Display; e.g.:
385 .nf
386
387         nvidia-settings --query localhost:0.0/DigitalVibrance[DFP-1]
388
389 .fi
390 An attribute name may also just be prepended with the screen number and a forward slash:
391 .nf
392
393         nvidia-settings --query 0/DigitalVibrance[DFP-1]
394
395 .fi
396 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).
397 If no X screen is specified, then the attribute value will be queried for all X screens.
398 .PP
399 Attributes can be addressed through "target types".
400 A target type indicates the object that is queried when you query an attribute.
401 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.
402 .PP
403 Target types give you different granularities with which to perform queries and assignments.
404 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.
405 .PP
406 A target specification is contained within brackets and consists of a target type name, a colon, and the target id.
407 The target type name can be one of
408 .B screen,
409 .B gpu,
410 .B framelock,
411 .B vcs,
412 .B gvi,
413 or
414 .B fan;
415 the target id is the index into the list of targets (for that target type).
416 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.
417 .PP
418 For example, the following queries address X screen 0 on the localhost:
419 .nf
420
421         nvidia-settings --query 0/VideoRam
422         nvidia-settings --query localhost:0.0/VideoRam
423         nvidia-settings --query [screen:0]/VideoRam
424         nvidia-settings --query localhost:0[screen:0]/VideoRam
425
426 .fi
427 To address GPU 0 instead, you can use either of:
428 .nf
429
430         nvidia-settings --query [gpu:0]/VideoRam
431         nvidia-settings --query localhost:0[gpu:0]/VideoRam
432
433 .fi
434 See the output of
435 .nf
436
437         nvidia-settings --query all
438
439 .fi
440 for what targets types can be used with each attribute.
441 See the output of
442 .nf
443
444         nvidia-settings --query screens --query gpus --query framelocks --query vcs --query gvis --query fans
445
446 .fi
447 for lists of targets for each target type.
448 .PP
449 The
450 .B \-\-assign
451 option can be used to assign a new value to an attribute.
452 The valid values for an attribute are reported when the attribute is queried.
453 The syntax for
454 .B \-\-assign
455 is the same as
456 .B \-\-query,
457 with the additional requirement that assignments also have an equal sign and the new value.
458 For example:
459 .nf
460
461         nvidia-settings --assign FSAA=2
462         nvidia-settings --assign 0/DigitalVibrance[CRT-1]=9
463         nvidia-settings --assign [gpu:0]/DigitalVibrance=0
464 .fi
465 .PP
466 Multiple queries and assignments may be specified on the commandline for a single invocation of
467 .B nvidia\-settings.
468 .PP
469 If either the
470 .B \-\-query
471 or
472 .B \-\-assign
473 options are passed to
474 .B nvidia\-settings,
475 the GUI will not be presented, and
476 .B nvidia\-settings
477 will exit after processing the assignments and/or queries.
478 .SS 5. X Display Names in the Config File
479 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.
480 For example:
481 .nf
482
483         nvidia-settings --query FSAA
484         nvidia-settings --query 0/FSAA
485         nvidia-settings --query stravinsky.nvidia.com:0/FSAA
486
487 .fi
488 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.
489 .PP
490 The same possibilities are available in the
491 .I ~/.nvidia\-settings-rc
492 configuration file.
493 .PP
494 For example, in a computer lab environment, you might log into any of multiple
495 workstations, and your home directory is NFS mounted to each workstation.
496 In such a situation, you might want your
497 .I ~/.nvidia\-settings-rc
498 file to be applicable to all the workstations.
499 Therefore, you would not want your config file to qualify each attribute with an X Display Name.
500 Leave the "Include X Display Names in the Config File" option unchecked on the
501 .B nvidia\-settings
502 Configuration page (this is the default).
503 .PP
504 There may be cases when you do want attributes in the config file to be qualified with the X Display name.
505 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
506 .B nvidia\-settings
507 Configuration page.
508 .PP
509 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.
510 .SS 6. Connecting to Remote X Servers
511 .B nvidia\-settings
512 is an X client, but uses two separate X connections: one to display the GUI, and another to communicate the NV-CONTROL requests.
513 These two X connections do not need to be to the same X server.
514 For example, you might run
515 .B nvidia\-settings
516 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:
517 .nf
518
519         nvidia-settings --display=bartok.nvidia.com:0 \\
520             --ctrl-display=schoenberg.nvidia.com:0
521
522 .fi
523 If
524 .B \-\-ctrl-display
525 is not specified, then the X Display to control is what
526 .B \-\-display
527 indicates.
528 If
529 .B \-\-display
530 is also not specified, then the
531 .I $DISPLAY
532 environment variable is used.
533 .PP
534 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
535 .B nvidia\-settings
536 (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).
537 .PP
538 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
539 .B nvidia\-settings.
540 .nf
541
542         (issued from bartok.nvidia.com)
543         xhost +stravinsky.nvidia.com
544
545         (issued from schoenberg.nvidia.com)
546         xhost +stravinsky.nvidia.com
547
548 .fi
549 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.
550 .PP
551 Please see the
552 .BR xauth (1)
553 and
554 .BR xhost (1)
555 man pages, or refer to your system documentation on remote X applications and security.
556 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:
557 .sp
558 .ti +5
559 .URL http://www.tldp.org/HOWTO/Remote-X-Apps.html
560 .sp
561 Please also note that the remote X server to be controlled must be using the NVIDIA X driver.
562 .SS 7. Licensing
563 The source code to
564 .B nvidia\-settings
565 is released as GPL.
566 The most recent official version of the source code is available here:
567 .sp
568 .ti +5
569 .URL ftp://download.nvidia.com/XFree86/nvidia-settings/
570 .sp
571 Note that
572 .B nvidia\-settings
573 is simply an NV-CONTROL client.
574 It uses the NV-CONTROL X extension to communicate with the NVIDIA X server to query current settings and make changes to settings.
575 .PP
576 You can make additions directly to
577 .B nvidia\-settings,
578 or write your own NV-CONTROL client, using
579 .B nvidia\-settings
580 as an example.
581 .PP
582 Documentation on the NV-CONTROL extension and additional sample clients are available in the
583 .B nvidia\-settings
584 source tarball.
585 Patches can be submitted to linux-bugs@nvidia.com.
586 .SS 8. TODO
587 There are many things still to be added to
588 .B nvidia\-settings,
589 some of which include:
590 .TP
591 -
592 different toolkits?
593 The GUI for
594 .B nvidia\-settings
595 is cleanly abstracted from the backend of
596 .B nvidia\-settings
597 that parses the configuration file and commandline, communicates with the X server, etc.
598 If someone were so inclined, a different frontend GUI could be implemented.
599 .TP
600 -
601 write a design document explaining how
602 .B nvidia\-settings
603 is architected; presumably this would make it easier for people to become familiar with the code base.
604 .PP
605 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.
606 .SH FILES
607 .TP
608 .I ~/.nvidia\-settings\-rc
609 .SH EXAMPLES
610 .TP
611 .B nvidia\-settings
612 Starts the
613 .B nvidia\-settings
614 graphical interface.
615 .TP
616 .B nvidia\-settings \-\-load\-config\-only
617 Loads the settings stored in
618 .I ~/.nvidia\-settings\-rc
619 and exits.
620 .TP
621 .B nvidia\-settings \-\-rewrite\-config\-file
622 Writes the current X server configuration to 
623 .I ~/.nvidia\-settings\-rc
624 file and exits.
625 .TP
626 .B nvidia\-settings \-\-query FSAA
627 Query the value of the full-screen antialiasing setting.
628 .TP
629 .B nvidia\-settings \-\-assign RedGamma=2.0 \-\-assign BlueGamma=2.0 \-\-assign GreenGamma=2.0
630 Set the gamma of the screen to 2.0.
631 .SH AUTHOR
632 Aaron Plattner
633 .br
634 NVIDIA Corporation
635 .SH "SEE ALSO"
636 .BR nvidia\-xconfig (1)
637 .SH COPYRIGHT
638 Copyright \(co 2006 NVIDIA Corporation.