
                    libfg - Frame Grabber Library
                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Details
~~~~~~~

    Version:            0.3a

    Author:             Gavin Baker <gavinb@antonym.org>

    Homepage:           www.antonym.org/libfg

    License:            Lesser GPL v2.1 (LGPL)

    Description:        Provides a simple high-level C interface to control
                        Video4Linux compatible hardware such as frame grabbers
                        TV tuners and USB cameras.


License Terms
~~~~~~~~~~~~~

    libfg - Frame Grabber library for Linux
    Copyright (C) 2002, 2003 Gavin Baker

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

    This library 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
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
    or visit their website at http://www.gnu.org/.


Introduction
~~~~~~~~~~~~

This library provides a simple C interface for controlling a frame grabber,
TV tuner card or USB webcam under Linux.  It uses the Video 4 Linux API for
control.  It supports the following features:

    - Frame capture (for image processing)
    - Video overlay (coming soon!)
    - Picture control
    - TV tuner control


Documentation
~~~~~~~~~~~~~

The API reference is provided in the doc directory, in HTML and PDF formats.


Building
~~~~~~~~

Current version uses simple Makefile, autoconf support is in the works.
For now, static library only.


Hardware Support
~~~~~~~~~~~~~~~~

Libfg should work with any V4L supported hardware, but is completely
dependent upon the version of the kernel you are using.  A recent 2.4 series
kernel is strongly recommended.

Known working devices:

    - BT848/BT878 capture card

    - TV tuner with Philips chipset

    - Logitech USB camera

It has been tested to work with the following configurations:

    - Debian woody 3.0, kernel 2.4.17, bttv driver, FlyVideo 98 card

    - Mandrake 8.2, kernel 2.4.19, bttv driver, Picolo card

    - RedHat 8

    - Debian woody 3.0, kernel 2.4.21, Logitech USB Camera

A note on FireWire support
--------------------------

FireWire (aka IEEE-1394) devices use completely different drivers and kernel
support, and have a totally different API to Video4Linux.  These devices are
not directly supported.

However - it should be possible to use a FireWire camera by using the
vloopback driver.  Set up your FireWire device as normal, and use the
loopback driver to pipe the 1394 digital video stream into a V4L device. See
the vloopback page for the details:

  - http://www.lavrsen.dk/twiki/bin/view/Motion/VideoFourLinuxLoopbackDeviceAPI


Python Bindings
~~~~~~~~~~~~~~~

A very preliminary release of bindings to Python are now included.
Methods will be gradually added over time.

Currently the extension must be manually built.  Fortunately, this is
only slightly harder than falling off a log.  It does require that you
have a recent (eg. 2.x) version of Python installed, with distutils.
And of course, you must build libfg first!

% python setup.py build

This will build the module and put it in a strange directory, like
build/lib.linux-i686-2.1.  If you go there and run the python interpreter,
you can do stuff like this:

>>> import fg
>>> g = fg.Grabber()
>>> g.set_source(0)
>>> g.set_channel(64.250) # ABC TV
>>> g.demo('test01.pgm')

Have fun!
