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 : where is the same name as given on the settings page, and 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 :., 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 :, 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___, 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.