    TVscreen and xtvscreen X11 applications for the
    bttv - BT848 frame grabber

    Copyright (C) 1996,97 Ralph Metzler  (rjkm@thp.uni-koeln.de)
                        & Marcus Metzler (mocm@thp.uni-koeln.de)

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


The files TVscreen.c TVscreen.h and TVscreenP.h define a new
widget class (the tvscreenWidgetClass) which is compatible to the
Xt toolkit. ( One does not need Motif to use the Tvscreenwidget.)
It is meant to provide an easy way to incorporate the "TVscreen"
in X11 applications. The size, positions, TV norm, input, brightness,
etc of the "TVscreen" can all be set via the resources of the WidgetClass.

Since the tvscreenWidgetClass is subclass of the coreWidgetClass all
its functionalities are inherited. In addition to that we provide
resources to set the tuner frequency, the input select of the bt848 and
various other settings like color. The clipping of the "TVscreen" is
also handled by the Widget itself. The following list gives an overview
of the resources provided up until now:

"devname"   is a string that defines the device name, e.g /dev/bttv, of the
	    bt848 driver. This is useful if you have more than one grabber
            card in your system.

"capture"   is a boolean that switches the capturing on or off.

"norm"      is an integer that switches the television norm:
	    0 = PAL
	    1 = NTSC
            2 = SECAM

"freq"      is an integer that sets the frequency of the tuner:
	    freq in MHz = freq/16

"inpsel"    is an integer that selects the input ( used to be "input", was
	    changed for compatibility reasons):
	    0 = tuner
            1 = composite 1
	    2 = composite 2
	    3 = SVHS

"delay"     is an integer that sets the delay between a refresh request and
            a refresh.

"bright"    integer that controls brightness.

"col"       integer that controls color.

"hue"       integer that controls hue.

"contrast"  integer that controls contrast. 

"refresh"   is a boolean that switches the refreshs made by the widget
            on or off (is not really useful yet).

"devname"   is string for setting the bttv device name, e.g. /dev/bttv1 for 
            your second grabber card.

"visname"   is a string for setting the name of the visual, e.g. TrueColor.
	    One can also use a hex number (e.g. 0x22) to enter
            the visual ID, or an integer preceded by a "c" 
	    (e.g. c4) to enter the visual class directly.

 "bpp"      is an integer for setting the bpp for cards that do not recognize 
            them correctly.

	

So if you want to write your own X11 application you can use the
TVscreenWidget and its resources to control the bt848.

The xtvscreen program is an X11 application using Motif that makes
use of the TVscreenWidgetClass. It provides a user interface to
control the resources of a TVscreenWidget. 

The menubar has two pulldown menus (The helpmenu has no real function
yet). The first one ("file") gives access to the quit button. (I guess
you know what that ones  for.) The second one ("start") has four
buttons. The first one ("capture") toggles the capturing on or
off. 

ATTENTION: You have to set capturing to on in order to get a picture.
The default is set to off, because we want to avoid any premature
program crashes. The driver is still being tested, so it is necessary
to have some more control over the program, especially if you want to debug it.


The second button ("control") pops up the control panel and the
third ("channel") pops up the channel selector.
In addition to that there are also 4 buttons that allow you to select
the input of the grabber card.

The fourth button is for fixing the aspect ratio.

The Snapshot button saves the current image to a file with name
"picxxx.jpg" where xxx is the running number of the snapshots take.
Careful it always starts with 000.

The control panel is split into two parts. In the upper half you can
control the input, the TV norm, the refresh delay and picture
characteristics like color and hue. In the lower part are  the tuner
controls. Here you can set the frequency of the channels and define
new TV channels. If you have found a new channel and want to add it
to the channel list simple type in the name you want to give it and
click on "Add channel" and the channel selector pops up with the
new channel added to  the channel list.

The channel selector window provides you with the ability to
save and load your channel settings and to delete channels. I think
it is pretty much self explanatory.

The relation between channel and actual frequency depends on the country
you live in. xtvscreen provides the possibility to load a file
describing this relation. Furthermore, one can set a default by
setting the constant DCOUNTRY in the globs.h file. The countries
you can choose from are also listed in globs.h.

xtvscreen provides the following command line options:

   -norm <NORM>      for setting the tv norm at startup, e.g. NTSC=1
   -input <INPUT>    for setting the input at startup, e.g. SVHS=3
   -dev <"devname">  for setting the bttv device name, e.g. /dev/bttv1 for 
                     your second grabber card.
   -v    <"Visual">  for setting the name of the visual, e.g. TrueColor.
	             One can also use a hex number (e.g. 0x22) to enter
                     the visual ID, or an integer preceded by a "c" 
	             (e.g. c4) to enter the visual class directly.
   -bpp <bits/pixel> for setting the bpp for cards that do not recognize 
                     them correctly
   -capon            for setting capturing on at startup 
                     (default is off).
   -rw   <width>     for setting the width of the screen in pixels
                     it is not reported correctly by the xserver.
   -asp  (0/1/2)     determines the aspect ratio used by the "Fix x/y"
                     button. (0= default, 1=4/3, 2=16/9)
   -disableSaver
   -dontDisableSaver to disable screen saver (or not) during the use of 
	             xtvscreen. Default is disable.
                     (added using code suggestions from Joerg Schneider)
   -country <file>   to set the channel <-> frequency relation via file      
                     see Europe.chan or USA.chan as example.
   -full             sets snapshot to full screen size.
   -snap <snapName>  set name for snapshot file
   -seq <snapName>   set name for sequence file 

If you have suggestions about improving the interface please e-mail us.
