USING NVTV
==========

There are three ways to run nvtv:

* Run nvtv as root.

* If there is a running closed source 'nvidia' X driver present, you may 
  start as non-root with option -N or --nvdev, and use the /dev/nv* devices 
  for accessing the card. 

  WARNING! If there is no running closed source 'nvidia' X driver, for 
  example if you have switched to the open source 'nv' driver, this will 
  cause a SYSTEM CRASH due to a bug in the NVidia kernel driver! Don't blame 
  me if that happens.

* Run the server nvtvd as root, for example on startup by including
  it in rc.S, and run nvtv as normal user.

After starting nvtv, you will see a notebook with six pages.


The Mode page (and how to use DVD modes)
-------------

The "Mode" page allows you to select one of the predefined modes. 
As a general rule, "Small" and "Tiny" are underscan modes, and
"Large" and "Huge" are overscan modes. "Normal" just fits
the visible surface of my TV, though this will probably be different
for your TV. If you are not satisfied with the predefined modes
and have the Brooktree chip (look at the Config page to find out if
you do), then you can make your own modes, as many as you like.

For the Chrontel chip, there are special convenience modes for DVD.
All of them require the NVidia video scaler, which is available with
the NVidia X driver, and is used by most DVD playing programs.  A PAL
DVD (with 720x576 data) scales to 768x576 in 4:3 mode and to 800x405
in anamorphic 16:9 mode, so you should use these sizes for your video
window and as a mode. For a PAL TV, both "Large" and "Small" are
available, since the "Large" mode has color flickers on my system,
though it would be the better choice. For an NTSC TV, there is only
the "Large" mode. All these modes are based on the 800x600 modes, and
just cut off the extra pixels.

For a NTSC DVD (with 720x480 data), scale it to 640x480 in 4:3 mode
and again to 800x480 in anamorphic 16:9 mode.

If your TV supports widescreen, you can also use an anamorphic 16:9
DVD as if it was in 4:3, and than switch your TV manually to widescreen.
This will give better results than the 800x405 mode.

The rationale behind using this modes is that on the one hand,
the number of lines will not be changed in the scaling process, and
if you use the "Large" modes it won't be changed when displaying it
on the TV, either. So no vertical distortion that is introduced by
the scaler can occur. Since the Chrontel chip cannot be programmed
to scale in horizontal direction, the horizontal scaling cannot
be avoided. On the other hand, the lower number lines compared to
the 800x600 modes will enlarge the vertical blanking interval, and will
give the driver more time to complete the things it has to do in this
interval.


The buttons on the bottom available for every page. "TV on" will
switch the tv-out mode on, "TV off" will switch it off again.
If you want to change anything while in tv-on mode, the changes
will only take effect after pressing "Apply", or by enabling "AutoApply".  

Finally, there is some additional functionality on the "Mode" page: "X
Video Mode" switches to an X mode that is equal or somehwat larger
than the resolution you have chosen. "X Window select" selects and "X
Window center" centers a window on the X virtual viewport (of course
only if the maximal X resolution is bigger than your current X video
mode resolution). You can also resize the selected window.


The Settings page
-----------------

The "Settings" page allows you to modify some register settings in an
intuitive way. These changes are not visible in the register pages,
and will only take effect when 'applied' or 'auto applied'.  Settings
include:

* The position of the image on the TV and the monitor. You can adjust
  that to some extent, but too large values will give strange results.

* Color and brightness of the TV image, from 0% to 200% of the
  original values. This directly influences the way the TV signal is
  generated, and should be used with care. Again, extreme values might
  give strange results and should be avoided.

* Saturation and contrast of the TV image. They have similar effect
  as color and brightness. TThey may not be always available, depending
  on the chip used, but if available, they should be preferred, because
  they offer don't distort the TV signal.

* Bandwidth. It controls the horizontal bandwidth of the luminance
  and chromance signal by selecting the appropriate low pass filters
  of the tv chip. The default value is 100%. Changes are usually not
  visible.

* Flicker filter. Will control the anti-flicker filter feature of the
  TV chip, the compensates for the flicker caused by small horizontal
  lines in the interlaced image. Filtering trades off vertical resolution 
  against flicker. You should use small values for movies etc, and middle to
  high values for text output. 

* Sharpness (text enhancement) filter. Not always available, depends
  on the TV chip.

* Dualview. This option will show the image on both the TV and the monitor. 
  There are modes where it seems to be impossible to get a monitor image, 
  or at least I could not find proper CRTC values; for these modes (esp. 
  the "Huge" ones) Dualview will be off by default. 

* Macrovision. By default, nvtv will turn macrovision off, if it can.
  If you want it for some reason, set this option. For Chrontel chips,
  it is not possible to enable Macrovision in all modes.


The Config page
---------------

The "Config" page shows in the "Hardware" frame your PCI card and
type. Here you can also select one card if you have more than one
NVidia card installed.  It also shows all TV chips found on both I2C
busses of the current card. If it cannot find a known TV chip, it will
list all devices found by bus address, so you can try to identify your
chip, find a datasheet somewhere and write some support routines for
new chips (if you want to).

In the "Connector" frame, you can probe if your TV is connected to the
card by the FBAS (also called "Composite" or "CVBS") line or by the
S-VHS (Super VHS) line, and you may change the output format if the
autodetction values are wrong. On this page there is also a list of
all keyboard acceleraters (hotkeys).

The next few pages depend on your TV chip. You will normally
use them only if you have at least read the datasheet of the
chip and know what you are doing.


The BT Calc page
----------------

On the "BT Calc" page, you can calculate your own modes for the
Brooktree chip. Enter the desired horizontal and vertical resolution,
together with a range for possible overscan percentage. The overscan
percentage determines the fraction of the image that is blank. As on
every TV some amount of the full image is "outside" the visible
screen, and not shown, for a "desktop" display the overscan values
should be large enough to avoid cutting of the edges of the image. For
movies, you want the picture as big as possible, and it does not
matter if the edge is missing, so you can use larger values.

Not all overscan percentages are possible, so press "List" to see a
list of valid ones. Badness shows how far they are away from the
desired overscan value (the center of the range), and Aspect is the
ratio of the x size divided by the y size of the resulting image. The
aspect ratio should be close to 1.  Choose a possible overscan value
line, and then press "Calc" to calculate the corresponding register
settings.


Register pages
--------------

The "CH Regs", "BT Regs", "BT Flags" and "CRTC Regs" pages give you
direct access to the registers of the Chrontel chip, the Brooktree
chip and the CRT-Controller chip, respectively. Read the documentation
of the BT chip before touching anything on the "BT Regs" page. Most of
the "BT Flags" values are overriden by the "Settings" page
values. However, the CRTC register might need some adjustment to
center the image on your TV and your monitor. See timing.txt for the
effects of changing some of those values.

Finally, the "Status" page show some frequencies for the monitor (be
sure your monitor can handle those, otherwise unselect the "Dualview"
option), and the status of the TV chip. For the Brooktree chip, if a
FIFO overrun/underun is indicated, chances are good that your tv image
is not very nice and you need to change the register values.
For the Chrontel chip, you may use the CIV value as the color
frequency value (FSCI).


Command line options
~~~~~~~~~~~~~~~~~~~~

You can get a list of all options with the option -?, -h or --help.
Here are some examples how to use them.

Specify a TV mode by size, and switch the TV on:

  nvtv -t -r 800,600 -s Normal

Specify a TV mode by overscan (not implemented yet), and switch TV on:

  nvtv -t -r 720,576 -o 11.3,5.4 

As a normal non-root user, specify a TV mode by size and chip, and print 
the mode (as root, you can drop the -n, and the chip will be detected):

  nvtv -n -p -r 640,480 -s Small --chip Brooktree

Switch TV off, using last X mode if available.

  nvtv -m

Switch TV off, using the last first available 800x600 modeline, and do an 
X mode switch to the same modeline afterwards (just in case).

  nvtv -m -X -r 800,600

Note: Switching the TV off by commandline will always fail without the
XVidMode extension present.

Switch to the first available 1024x768 modeline (and fail otherwise),
as normal non-root user:

  nvtv -X -r 1024,768

Center window, also as non-root user:

  nvtv -n -w "xine video output" -c

Switch X mode, then switch TV on with the specified mode, and center the
window:

  nvtv -t -X -r 800,600 -s Large -w "xine video output" -c

If the TV is off, display color bars and the tv, and keep the monitor
as it is. If the TV is on, do nothing.

  nvtv -b

Switch the TV on, use the default 800x600 resolution in 'Large' size,
and set the connector to 'convert' to use a luminance-only S-VHS to FBAS
converter cable (see FAQ):

  nvtv -t -s Large -C convert

Switch the TV on, with same mode as above, and set flicker filter to
25 percent (for example for watching DVDs):

  nvtv -t -s Large -f 25

This also works when the TV is already on if you want to change the
flicker filter setting, but it will change the resolution and size
if you specifiy a mode different than the current one. It is not
possible to omit resolution (it will default to 800x600) or size.


Making a new mode
~~~~~~~~~~~~~~~~~

Here's a brief step by step description how to create a new mode for
the Brooktree chip.  Choose the "BT Calc" page, enter the resolution
(say, 768x576), choose an overscan range, and press "List". Pick a
line (say 10.5% horizontal and 4.2% vertical), and press "Calc". Now
press "TV on" or "Apply" (unless you have AutoApply enabled).  Switch
to the "CRTC Regs" page, and adjust the horizontal and vertical
"SyncStart" values until the image is more or less centered on the
monitor. Make sure that "SyncEnd" has a reasonable value (my monitor
seems to ignore the end of the sync pulse, but yours may not). Adjust
the "Total" registers in a similar way to center the image on the
TV. The "hoffset" register on the "BT Regs" page can also be used to
move the TV image horizontally. Finally, press "Print" on the
appropriate page(s) to print the register settings to stdout. You can
include them in the data.c file, if you like.

The initial CRT values may be way off, or may be so bad that you don't
even get a picture. Switching X video modes (CTRL-ALT + and - keys on
the numpad) *might* bring at least the TV image back.  You're down to
trial and error in this case.  See timings.txt for some details.

If you have successfully created a new mode, and you think others
would like it to use as well, please send an email to
dthierbach@gmx.de. Include BT and CRTC registers, resolution,
overscan, and a brief visual description (e.g., "on my Panasonic XYZ
TV it touches just the edges and is perfect. On the monitor, it's just
ugly.") of this mode. I probably won't be able to answer your email,
but I might include this mode in a database for the next release.


Plugins for other programs
~~~~~~~~~~~~~~~~~~~~~~~~~~

The server makes it easy to write plugins for other programs, for
example xine, that allow those program to switch to TV out without
having to run them as root. However, none of the plugins have been
written yet, but the possibility is there.


