[ libbgrab - easy to use bttv interface library ]


(C) under the GPL, A. Schiffler
schiffler@zkm.de

Please see the file LICENSE for GPL info.


[ Introduction ]

libbgrab is a video4linux grabbing library to facilitate easy use of BTTV
framegrabber cards through a few function calls. To implement constant
throughput and to avoid frame loss delays, triple buffering is used through
local buffer copying in a separate grabbing thread.

See demo program "testgrab" for a quick intro on how to use libbgrab. See
source code comments for additional usage notes.

Also included is a demo "asciigrab" that converts video in realtime into 
ASCII - just start it in a large enough terminal ... . See source code for
additional usage notes.

Also included is a demo "zoomgrab" that shows a live video image at any
scale using a 3dfx graphics card (required). The numbers in "zoomdef.txt" 
define zoom scales in ONE SECOND intervals (range: 0.01 to 200.0, first 
number in line) and mixer volume settings (range: 0 to 100, second number 
in line) that will be smoothly applied to the image and the volume. See
source code for additional usage notes.

A similar demo called "artcam" also uses glide for display. This demo
changes the colors of an image in realtime using a precalculated 
conversion table.


[ Version History ]

Ver. 1.0 - Sun Apr 18 19:16:13 CEST 1999
* Initial release.

Ver. 1.1 - Sun Apr 25 11:49:18 CEST 1999
* Complete rewrite of the buffering code. Much simpler - same effect.
* Changed function names to fg_...
* Added xutil components to library for easy shm-Xwindow creation (this 
component is as of this version incomplete).

Ver. 1.2 - Wed Apr 28 11:12:39 CEST 1999
* Added syncronization conditional to limit image polling at actual FPS
* Completed xutil component
* Added proper SHM removal function
* Added keyboard hook function to xutil.c
* New demo-program "asciigrab" added

Ver. 1.3 - Tue May 18 15:01:08 CEST 1999
* Changed testgrab to accept a device name
* Changed windows-routine to use PID as SHM identifiert

Ver 1.4 - Sun Jun 20 17:38:57 CEST 1999
* Added spline code 
* Added zoomgrab application

Ver 1.5 - Wed Jul 21 09:48:55 CEST 1999
* README updated
* Added mouse position to xutil keypoll-callback
* Fixed volume control in zoomgrab (was mono, is stereo now)

Ver 1.6 - Wed Aug 25 10:37:15 CEST 1999
* Added artcam application
* Fixed volume bug in zoomgrab


[ Usage - Step-by-Step Instructions  ]

1. Define a variable with this structure and use as pointer as handle for all
accesses to the library.

struct fgdevice { ... }

2. Use these calles to open the device. Typical device name is /dev/video.

int fg_open_device (struct fgdevice *fg, char *devicename);
int fg_close_device (struct fgdevice *fg);

3. Use this call to retrieve general info and a channel list of the card. 

int fg_print_info(struct fgdevice *fg); 

4. Before grabbing, set the update interval for FPS calculation. FPS is the
rate of image retrieval using fg_get_next image.

void fg_set_fps_interval(struct fgdevice *fg, int interval);
double fg_get_fps(struct fgdevice *fg);

5. Define the setting and channel values.

int fg_get_setting(struct fgdevice *fg, int which_setting);
int fg_set_setting(struct fgdevice *fg, int which_setting, int value);
int fg_set_channel(struct fgdevice *fg, int channel);

#define SETTING_BRIGHTNESS	0
#define SETTING_HUE		1
#define SETTING_COLOUR		2
#define SETTING_CONTRAST	3

6. Initiate grabbing at a specific size and format using the
fg_start_grab_image call. Grabbing will constantly run in a thread. Retrieve
the latest image through the fg_get_next_image call. 

int fg_start_grab_image (struct fgdevice *fg, int width, int height, int format);
int fg_stop_grab_image (struct fgdevice *fg);
void * fg_get_next_image(struct fgdevice *fg);

#define FORMAT_GREY		VIDEO_PALETTE_GREY
#define FORMAT_RGB565		VIDEO_PALETTE_RGB565
#define FORMAT_RGB32		VIDEO_PALETTE_RGB32


[ Compilation ]

* Make sure you have the required modules for video input loaded and the
video include "linux/videodev.h" available. 
* Optionally install glide libraries.
* Run "make". Test with "testgrab" (running XWindows at depth 16 weight 565).


[ Additional Components in the Library - xutil ]

These functions are added to the bgrab-library to facilitate easy X-Window
creation and use. See sample programs for details.

IMPORTANT NOTE: 
Crucial is the proper closure and removal of the X-Windows shared 
memory segment in the close_xwinbuffer function. After abnormal program
termination, one has to manually remove the SHM-segment using "ipcs" (to
check for the SHM ID) and "ipcrm shm ID" (to actually remove the segment). 

int setup_xwinbuffer(struct xwinbuffer *xwin, char *prgname, int width, int height, int depth);
int sync_xwinbuffer(struct xwinbuffer *xwin);
int close_xwinbuffer (struct xwinbuffer *xwin);
int keypoll_xwinbuffer (struct xwinbuffer *xwin, KeySym *key, int *button, int *mousex, *mousey);

To implement keyboard/mouse functionality use the following code fragment.

// Sample keyboard polling
// ...
 KeySym key;
 int button;
 int x,y;
// ...
  /* Poll keyboard */
  if (keypoll_xwinbuffer (&xwin, &key, &button, &x, &y)) {
     /* Check for mouse button press */
     if (button) {
      printf ("Mouse was pressed at coordinate (%i,%i)\n",x,y);
     }
     /* Check for keyboard press +/
     switch (key) {
      case XK_Home:
       break;
      case XK_Left:
       break;
      case XK_Right:
       break;
      case XK_Up:
       break;
      case XK_Down:
       break;
//     ...
      case XK_q:
       break; 
     }
    }