libpwc - Small library for Philips Webcam Linux Driver
------------------------------------------------------

This is a small library used to decode the raw compressed stream send by the
linux pwc driver. Currently the library is only a wrapper aroung the linux
kernel code, but in the future we can write the decompressor using assembler or
a faster decoder.

I've made a small example how to decode the stream sent by the linux driver. In
the future, i'll produce a real example that grab and image, convert it, and
output in a known format.

Stream format
-------------

Currently the format return by the driver is not the raw format, but i've add a
small header (8 bytes), to help decoding it.

struct pwc_raw_frame {
   __le16 type;         /* type of the webcam (645, ..., 750)                   */
   __le16 vbandlength;  /* Size of 4lines compressed (used by the decompressor) */
   __u8   cmd[4];       /* the four byte of the command (in case of nala
			   version, only the first 3 bytes is filled)
   __u8   rawframe[0];  /* frame_size = height/4*vbandlength */
} __attribute__ ((packed));

The library use this information to decode the image, but one information is
missing, is the size of the image. We the size of the buffer, and the
information present in the header, i think we can reconstruct these informations.

Example - testlibpwc
--------------------

  testlibpwc is the main program to give an exemple how to use the library.

# ./testlibpwc
Usage: ./testlibpwc [options]

Options:
-I | --fmti   FORMAT Format of the input file (raw)
-i | --input  FILE   File to convert
-O | --fmto   FORMAT Format of the output file (yuv, rgb, tga)
-o | --output FILE   File to write the image
-s | --size   WxH    WIDTHxHEIGHT (by default 640x480) 

Version: 0.1.0
Copyright: Luc Saillard
Licence: LGPL (contains some code from the ffmpeg project)





How to use this library:
------------------------

 error is always negative, and 0 is ok

* libpwc_decode_simple(width, height, input_buffer, output_format, &output_buffer)

   In one call, this function decode the rawstream, into an useable format.
   @param width: width of the image
   @param height: height of the image
   @input_buffer: rawstream returns by the V4L2 interface (including the header)
   @output_format: select the output format (V4L2_PIX_FMT_YUV420 
         or V4L2_PIX_FMT_RGB24)
   @output_buffer: pointer to dynamically array that will be allocated by the
         library. This pointer need to be free using free() in case of sucess.

* struct pwc_t *libpwc_init(void):
* void libpwc_init(struct pwc_t *pwc):
* libpwc_open(struct pwc_t *pwc, const unsigned char *devname):
* libpwc_close(struct pwc_t *pwc)


* int libpwc_decode(struct pwc_t *pwc, 
    		  const int raw_format, const unsigned char *rawstream, 
		  const int out_format, void **buffer) *
   @param pwc: handle on an already initialize pointer
   @param raw_format: used to determinate the decompressor to use.
   @param rawstream: the stream to uncompress
   @param out_format: can be V4L2_PIX_FMT_YUV420 or V4L2_PIX_FMT_RGB24
   @param buffer: address of an already allocated buffer. If you want the
   library to allocate the buffer set it to NULL. In this case, the buffer need
   to be free using free().
  


