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

There are three ways to run nvtv:

* Run nvtv as root. If you want, you can use sudo, or change the owner
  of the binary to root and set the set UID bit with chmod.

* 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. This seems only to work upto version 1.0-2840.

  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 a number of different
pages, which you can select on the left hand side.


The Mode page 
-------------

The "Mode" page allows you to select one of the predefined modes.
You should choose your TV system (it defaults to PAL), the
resolution and the size. 

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 or
Conexant encoder chip (look at the Config page to find out if you do),
then you can make your own modes, as many as you like.

The buttons on the bottom are available on 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
Mode" switches to an X mode that is equal or somehwat larger than the
resolution you have chosen. "X Select" selects an X window.  If there
is an selected window, its name is displayed.  "X 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). "X
Resize" resizes the selected window to the resolution. Pressing both
"center" and "resize" will therefore give you a "fullscreen" effect
for that window.

Note on the overscan compensation values (often just labeled overscan):
These values give the percentage of the full image that remains
unused. The larger the overscan compensation value, the smaller the
image. Usually, TV sets have an overscan compensation value of about
10%, which means that 10% of the image of every normal TV source
is not visible on the TV set by design. That means a mode with
overscan compensation of 10% will be fully visible on the TV screen.

Note on the Chrontel PAL-60 modes: These modes do not comply fully to
the standard (the color burst start is different), because the Chrontel
encoder chip was never designed to support PAL-60. Therefore, they
may not work satisfactory.


Special DVD modes
-----------------

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 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, but
it is only possible if your DVD playing program gives you full 
control about the window size. Some programs like Xine without patches
restrict the aspect to the aspect of the DVD.

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.

Similarly, there are special DVD modes for the Brooktree chip. Both
the 720x576 Pal DVD mode and the 720x480 NTSC DVD mode have very
little overscan an no vertical scaling, but a different aspect than
the usual 4:3. So to use it, you should be able to control the window
size without aspect restrictions.


More special modes
------------------

For the Chrontel encoder chip, modes ending with '#' are 'no-dot-crawl'
modes. They will attempt to reduce the 'dot-crawl'-effect seen in NTSC.
Otherwise, they are the same as the correspending mode without '#'.

Another suffix used is '+' for the 3:2 modes that are available 
with the Conexant encoder. For example, there are two 800x600 Small PAL
modes with different overscan compensation.


The Position page
-----------------

With this page, you can adjust the position of the image on the TV and
the monitor. These changes are not visible in the register pages, and
will only take effect when "applied" or "auto applied". Adjusting
these positions only works to some extent, and large values will
probably give strange results.

You can also move and resize the X window you have selected on the mode
page, in case your window manager doesn't allow precise numbers
for these changes.

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

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

* Contrast and saturation of the TV image, from -100% to 100%. 0% is
  the default value. These settings may not be always available, depending
  on the encoder chip used, but if available, they should be
  preferred, because they don't distort the TV signal.

* Brightness#, contrast# and saturation#, from -50% to 50%.
  This directly influences the way the TV signal is generated, and should 
  be used with care. Extreme values might give strange results and should 
  be avoided.

* Phase. The phase of the color carrier in degrees. If the color in the
  image "jumps" or is otherwise distorted, you can try to compensate it
  with this setting.

* Hue. Only available for Conexant encoder chips. This settings adjusts
  the hue, that is, the way different colors are encoded. Settings
  is in degrees, large values give a false-colors effect.

* Flicker filter. Will control the anti-flicker filter feature of the
  encoder chip, that 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
  medium to high values for text output (together with a high sharpness
  setting). The left slider is for the main anti-flicker filter, the
  right slider is for the adaptive anti-flicker filter available with
  Conexant encoders.

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

* Sharpness. The left slider controls the text enhancement filter (which
  makes text sharper and easier to read), the right slider controls
  cross color reduction. Both settings again may not always be available, 
  depending on the encoder 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. 

  Don't confuse "dual view" with "dual head": The first outputs the
  same image on both the monitor and the TV, driving the monitor at a
  low frequency. The second outputs two different images (usually
  different in size, but not necessarily different in content), one on
  the monitor with a higher frequency, and one the TV. So they have similar
  effects, but are quite different. Dualhead mode is described below.

* 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.

* Free carrier. Allows a free running color subcarrier generator, which is
  not reset every frame or every few frames (not implemented yet).

* Non-interlace. Only generate the first half-frame. Looses vertical
  resolution, but increases sharpness a lot. Only available for Brooktree
  and Conexant encoder chips.

* Colorfix. If the colors on the TV are very strange (Philips) or
  flickering (Chrontel), try this button.

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 encoder chips found on
all I2C busses of the current card. If it cannot find a known TV
encoder 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 Composite (also called "FBAS" or "CVBS") line or by the
SVideo (Super VHS, S-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 "Color bars" button in the "Test Image" frame will show the same
test image you get when starting up the program, if the encoder chip
supports it.


The Heads page
--------------

This page will only be available if you have a card with NV11
architecture that has two heads, e.g. GeForce2 MX/Quadro2 MX/GeForce2
GO and similar cards. If your card has two heads, but you don't see
this page, send me an email.

To enable the second head, the TV head number (usually 2) should be
different from the Monitor head number (usually 1). On the GeForce2 GO,
this might be different, but has not been tested yet. You can select
the TV head either on this page or with the command line options -1 and -2.

There are two basic ways to use the second head:

* Without Twinview. You have to enable "Shared view" to use the second
  head. In this case, the image on the monitor will be a copy of some
  part of the image of the screen. The "Viewport position" lets you
  choose which part to use. You can automatically adjust the viewport, 
  either "by Cursor", which will move the viewport whenever the cursor
  leaves the visible part, and/or "by Monitor", which will move the 
  viewport whenever the X viewport on the Monitor is moved.

* With Twinview. In this case, nvtv will automatically use the second
  head for any mode changes, so selecting a mode and pressing "TV on"
  can be used to get rid of the black borders and make the image larger.
  Additionally, you can enable "Shared view" like above, and choose
  freely the part of the virtual screen you'd like to see on the TV.

To handle the cursor correctly, there are again two cases, depending
on your preferences in your XF86Config file:

* Software cursor. This cursor will always be correcly displayed.

* Hardware cursor. If you are using Twinview (and did not enable
  Shared view), the cursor will behave properly. Otherwise, to be able to 
  see and move the cursor, you have to select "Adjust cursor". 
  If Twinview was active, both the nvidia driver and nvtv will try to move 
  the cursor, so sometimes the cursor might jump for a quick time to
  the wrong place.

Finally, the most important thing: The video overlay. If Twinview is
enabled, the nvidia driver uses the NV05 Video Blitter, which will
always display the video correctly (though not as efficiently as it
could). Otherwise, both the closed source and the open source driver
use the NV10 Hardware Overlay. This will only work on one head, which
you can choose by setting the "video head" field. Moreover, the position
of the overlay is determined by the driver and cannot be controlled by
nvtv. That means that the video window on the TV should have the same
relative position as on the monitor, otherwise only part of it will be
visible. To enforce this behavior, you should select "Adjust viewport
by Monitor", and also switch to an X mode that has the same or a similar 
resolution as the TV mode.


Encoder chip dependent pages
============================


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 (and CX) Calc page
-------------------------

On the "BT Calc" page, you can calculate your own modes for the
Brooktree and the Conexant 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 off 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
relative aspect of the image, that is, the ratio of the actual
horizontal size divided by the vertical size of the resulting image
with respect to the full screen (which itself has an absolute aspect
ratio of 4:3). If this is too difficult to understand, just remember
that the (relative) aspect ratio should be close to 1; the closer, the
better. The note field has in "8" if this is a character clock mode
(preferred), otherwise an "1" for a pixel clock mode, and an additional
"+" if it is an 3:2 clock mode.

You can sort any of the columns by clicking on the table heading.

Now choose a possible overscan value line, and then press "Calc"
to calculate the corresponding register settings.

All modes calculated in that way need some finishing: The image is
very probably not correcetly centered, because the HSync and VSync
values are just estimates. Go to the CRT and modify those values until
the results look allright. You can use the test image in tclkt/cross.tk
to help you with the centering.


The PH Calc page
----------------

Not documented yet. FIXME.


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

The "CH Regs", "BT Regs", "CX Regs", "PH Regs" and "CRTC Regs" pages
give you direct access to the registers of the Chrontel chip, the
Brooktree chip, the Conexant chip, the Philips chip and the
CRT-Controller chip, respectively. You should read the documentation of the 
tv encoder chip before touching anything on these pages. Some of the
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.


The Status page
---------------

Finally, the "Status" page shows 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 Large

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

If for some reason the TV is already active, you can use -F in conjunction
with -p to print the current mode:

  nvtv -F -p

Switch TV off, using last X mode if available.

  nvtv -m

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

  nvtv -m -X -r 800,600

Switch TV off, and use the specifed VESA mode as monitor mode.

  nvtv -m -s '800x600@75'

Note: Switching the TV off by commandline will always fail without the
XVidMode extension present, unless you give a VESA mode as above. But
this should only be used as a last resort, or under Windows, because the
video driver will not be properly initialized.

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 SVideo to
Composite converter cable (see FAQ):

  nvtv -t -s Large -C convert

Moreover, there are some options that take only effect when switching
the TV on. The first ones are the settings, that have the general form

  nvtv -t --set <name>:<value>

where <name> is the same name as given on the settings page, and
<value> must be inside the valid range. For example, to switch the TV
on, with same mode as above, and set flicker filter to 25 percent (for
example for watching DVDs):

  nvtv -s Large --set flicker: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.

In the same way, you can set the boolean options on both the settings
and the head page. For example,

  nvtv --set dualview:off --set viewportmonitor:on

starts the GUI with dualview disabled and adjusting the tv viewport by 
the monitor viewport enabled.

For dualhead cards, there are the switches -1 and -2 to select the
apropriate head.

If you have multiple cards in your system, you can use the -A or
--card-addr option to select the card you want to the command line.
Give the address in the format <bus>:<slot>.<func>, for example

nvtv -A 1:0.0

to select your AGP card.

Similarly, if you have multiple encoders reachable through the I2C
busses, you can select the encoder with --chip <bus>:<addr>, for example

nvtv --chip 1:8a

Instead of the bus address, you can also just use the encoder type
(brooktree, chrontel, conexant, philips).

If for some reason you cannot use the GUI, or you want to use nvtv in
a script, you can also get a list of available modes with --list or
-l. For example,

nvtv -l -T brooktree

lists all Brooktree modes, even if you cannot access the hardware. If
you omit the -T or --chip option, it will list the modes for the
hardware that is found.

Finally, you can query the state of the specified head with the -q option.
This is useful in a shell script. Nvtv both prints the result to stdout
and sets the exit code. The values are

0  Display disabled (not detected properly yet)
1  Monitor only
2  TV only
3  Monitor and TV (Dualview)
4  Flatpanel only

The exit code is 100 plus the above value (smaller exit codes denote
errors.)


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.

Also, especially for NTSC and PAL-60, not all the modes listed will
work, because underflow or overflow cannot be avoided. Check the
value of h_blanki; if it is very low or zero, you may be in trouble.

Finally, I recommend to fine tune your mode by adjusting h_blanki, to
make sure the complete image is displayed. You have to observe the
borders of the image to do this. As they are sometimes outside the
visible part of the TV, first temporarily reduce both HorizDisplay and
h_active to the same number to bring the right border well within the
right visible part of the TV screen. Then increase h_blanko to make
the left border also visible. Now, change h_blanki and watch the
image. While you decrease it, the image will move right, while on the
left border new pixel appear and the right border just moves. At some
point, the right border will start to disappear, while the left border
will show nothing new. This value is the right value for h_blanki.

A similar procedure can be used to adjust *HBlankStart for Voodoo
cards.


Inserting a new mode in the database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

All the modes are stored in the data*.c files. There is no per-user
or per-system database in seperate files yet, if you want to contribute
it, feel free to send in a patch.

Let's assume you have made or modified a mode for the Brooktree chip
on an NVidia card. The Brooktree encoder data is found in data_bt.c,
the NVidia related in data_nv.c.

In data_bt.c, you'll find lot's of TVBtRegs declarations, sorted by
TV system and resolution. Pick the appropriate place and include your
mode. The naming scheme is bt_<system>_<size>_<letter>, but you
can of course pick your own name. You'll also have to add a corresponding
'extern' declaration in data_bt.h.

In data_nv.c, first look for the part the deals with BT modes (marked
by double lines == BT ==). Then, add a TvNvRegs declaration in a
similar way as above.  Finally, you'll have to add a template entry
that contains the mode specification (system, resolution, size string,
aspect string, and amount of overscan), pointers to the BT and NV
data, the host and encoder port flags (normally, just use PORT_NVIDIA), 
description flags (use TV_DEF_BT_DUAL if it works with dualview, and
TV_DEF_BT otherwise), and additional parameters (in this case,
hsynoffset, see below).

Remake the source, and the mode should now be available. Other 
encoder/graphic card combinations work in a similar way.

Some special cases in this scheme:

BT/NV: The hsynoffset information is in the template. This register
sometimes causes trouble, though it is essential to keep both the TV and
the monitor image more or less centered. Hence you can adjust this
value without having to include BT or NV data.

CX/NV: The BT/NV templates are also used, the CX/NV template contains
just additional modes. Also, PAL modes are autoconverted to SECAM modes.

CH/NV: The templates contain a pointer to multiple FSCI values. For
50Hz modes, they are for PAL, PAL-N, and PAL-X (which is a pseudo system
since some TVs seem to need different values.) For 60Hz modes, they
are for NTSC, NTSC with no dot crawl, PAL-M, and PAL-60. The PAL-60 
modes don't work on my TV, however.


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,
preferably in diff -uw format.
In any case, include the encoder 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, so
other people can use it as well.


Laptops with LCD Displays
~~~~~~~~~~~~~~~~~~~~~~~~~

FIXME


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.