readme

基于SDL的framegrabber适用于简单的UI下的webcam应用开发

SDL_bgrab - SDL based v4l Video Grabbing Library
=============================================================================

Intro
-----

SDL convertion of libbgrab (a framegrabber lib from the same author).


The library uses a separate thread to grab images into a "triple buffer" 
queue independent of an external "game loop". This uses memory bandwidth
but makes it easy to integrate live video into other applications. 
Images are always grabbed at 32bit RGBx resolutions. YUV grabbing is 
currently not implemented. To improve image quality, several deinterlace 
algorithms are available.

Email [e-mail] to contact the author or better check
author's homepage at http://www.ferzkopp.net for the most up-to-date
contact information.

This library is licenced under the LGPL, see the file LICENSE for details. 


Supported Platforms
-------------------

The library compiles and is tested on a Linux target.

Windows will probably never be supported due to the lack of v4l API.
Other SDL platforms might be supported in the future if an API 
similar to v4l is available.


Installation and Test
---------------------

To compile the library your need the SDL 1.2 installed from source or 
installed with the 'devel' RPM package. For example on Mandrake, run:
	urpmi libSDL1.2-devel

The run
	./autogen.sh	(optional)
	./configure
	make
	make install
	ldconfig

to compile and install the library. The default location for the 
installation is /usr/local/lib and /usr/local/include. The libary 
path /usr/local/lib might need to be added to the file
	/etc/ld.so.conf
Then run ldconfig again.


API and Usage
-------------

Create a variable of type tSDL_bgrab and reference a pointer to it on every 
library call.


  int bgrabOpen(tSDL_bgrab *bgrab, char *device);

Open framegrabber device. "device" is usually "/dev/video"


void bgrabSetFpsInterval(tSDL_bgrab *bgrab, int interval);

  double bgrabGetFps(tSDL_bgrab *bgrab);

Query internal framerate tracker.


  int bgrabPrintInfo(tSDL_bgrab *bgrab);

Print v4l device info.


  int bgrabGetSetting(tSDL_bgrab *bgrab, int which_setting);
  int bgrabSetSetting(tSDL_bgrab *bgrab, int which_setting, int value);

Get and set device settings (contrast, brightness, etc.). See the SDL_bgrab.h
file for the relevant device for the "which_setting" variable.


  int bgrabSetChannel(tSDL_bgrab *bgrab, int channel, int bgrabmode);

Set the input channel (tuner, svideo, composite) and mode (pal, ntsc, secam)
for your device.


  int bgrabSetFrequency(tSDL_bgrab *bgrab, int region, int index);

Set the tuner frequency (when in tuner mode). See the SDL_bgrab.h file for
region settings.


  int bgrabStart (tSDL_bgrab *bgrab, int width, int height, int bgra);
  int bgrabStop(tSDL_bgrab *bgrab);

Start and stop the grabbing thread. The "width" and "height" parameters define
the size of the 32bit RGB buffer to use. Set the "bgra" flag to 1 for some
cards that store pixels in BGR order.


  int bgrabBlitFramebuffer(tSDL_bgrab *bgrab, SDL_Surface *screen, int deinterlace);

Blit the current franebuffer to a target surface. Set "deinterlace" to a number >1
to enable processing of the frame with various deinterlace algorithms. Use TestVideo
to see the various algorithms at work (and check their CPU usage).


  int bgrabClose(tSDL_bgrab *bgrab);

Close device. Be sure to call bgrabStop() before. 


Quickie Sample Program
----------------------

SDL_Surface *screen;
tSDL_bgrab bgrab;
int drawing;
// ... open screen ...
bgrabOpen(&bgrab,"/dev/video");
bgrabSetChannel(&bgrab, CHANNEL_COMPOSITE, VIDEOMODE_NTSC);
bgrabStart (&bgrab, 320, 240, 0);
drawing=1;
while (drawing) {
 if (bgrabBlitFramebuffer(&bgrab, screen,  1)) {
  SDL_UpdateRect(screen,0,0,0,0);
 }
 SDL_Delay(10);
}
bgrabStop(&bgrab);
bgrabClose(&bgrab);


Test Program
------------

Change to the ./Test directory and run
	./configure
	make
to creates a sample TV player. You can check and maybe edit the 
default settings in the source for your device and input.

Best is to see some command line options. Run:
	./TestVideo -help


Use the source code TestVideo.c for some sample code on how to 
create a simple TV viewer in your SDL app.


Development and To-Do
---------------------

Here is what I'd like to do.

* Implement a YUV mode for the lib.
* Make better use of v4l API capabilities 
  (i,e, when we have >2 mmap buffers, use them).
* Add faster (MMX) deinterlace routines.
* Add some other image-improvement and -modification 
  algorithms (greyscale, sharpen, soften, temporal smooth, etc.).


Thanks
------

Thanks to 'AppWares Development Group' for supporting this project - please 
visit http://www.appwares.com for more information.


Contributors
------------

* None so far. Want to be the first one ...??? Get coding!