This file contains some additional information for the Philips webcams.
E-mail: webcam@smcc.demon.nl                        Last updated: 2001-07-27

The main webpage for the Philips driver is http://www.smcc.demon.nl/webcam/.
It contains a lot of extra information, a FAQ, and the binary plugin
'PWCX'. This plugin contains decompression routines that allow you to
use higher image sizes and framerates; in addition the webcam uses less
bandwidth on the USB bus (handy if you want to run more than 1 camera
simultaneously). These routines fall under an NDA, and may therefor not be
distributed as source; however, its use is completely optional.

You can build this code either into your kernel, or as a module. I recommend
the latter, since it makes troubleshooting a lot easier. The built-in
microphone is supported through the USB Audio class.

(Taken from install.html)

When you load the module you can set some default settings for the
camera; some programs depend on a particular image-size or -format. The
options are:

size
   Can be one of 'sqcif', 'qsif', 'qcif', 'sif', 'cif' or
   'vga', for an image size of resp. 128x96, 160x120, 176x144,
   320x240, 352x288 and 640x480 (of course, only for those cameras that support these resolutions).

fps
   Specifies the desired framerate. Is an integer in the range of 4-30.

palette
   Specifies the desired colour order that should be delivered by read() and
   mmap(). The string can be one of yuv420 or yuv420p; however, yuv420 will
   be phased out, leaving only yuv420p, so this option will disappear
   entirely.

   Only the native yuv420/yuv420p format is supported by the in kernel driver. 
   If you want to use other formats with in-kernel conversion download the
   driver from the URL given. [Alan]

fbufs
   This paramter specifies the number of internal buffers to use for storing 
   frames from the cam. This will help if the process that reads images from 
   the cam is a bit slow or momentarely busy. However, on slow machines it 
   only introduces lag, so choose carefully. The default is 3, which is 
   reasonable. You can set it between 2 and 5.

mbufs
   This is an integer between 1 and 4. It will tell the module the number of
   buffers to reserve for mmap(), VIDIOCCGMBUF, VIDIOCMCAPTURE and friends.
   The default is 2, which is adequate for most applications (double
   buffering).
      
   Should you experience a lot of 'Dumping frame...' messages during
   grabbing with a tool that uses mmap(), you might want to increase if. 
   However, it doesn't really buffer images, it just gives you a bit more
   slack when your program is behind. But you need a multi-threaded or
   forked program to really take advantage of these buffers.

   The absolute maximum is 4, but don't set it too high!  Every buffer takes
   up 1.22 MB of RAM, so unless you have a lot of memory setting this to
   something more than 2 is an absolute waste.  This memory is only
   allocated during open(), so nothing is wasted when the camera is not in
   use.

power_save
   When power_save is enabled (set to 1), the module will try to shut down
   the cam on close() and re-activate on open(). This will save power and
   turn off the LED. Not all cameras support this though (the 645 and 646
   don't have power saving at all), and some models don't work either (they
   will shut down, but never wake up). Consider this experimental. By
   default this option is disabled.

compression (only useful with the plugin)
   With this option you can control the compression factor that the camera
   uses to squeeze the image through the USB bus. You can set the 
   parameter between 0 and 3:
     0 = prefer uncompressed images; if the requested mode is not available
         in an uncompressed format, the driver will silently switch to low
         compression.
     1 = low compression.
     2 = medium compression.
     3 = high compression.
      
   High compression takes less bandwidth of course, but it could also
   introduce some unwanted artefacts. The default is 2, medium compression.
   See the FAQ on the website for an overview of which modes require
   compression.
      
   The compression parameter only applies to the Vesta & ToUCam cameras.
   The 645 and 646 have fixed compression parameters.      

trace
   In order to better detect problems, it is now possible to turn on a
   'trace' of some of the calls the module makes; it logs all items in your
   kernel log at debug level.

   The trace variable is a bitmask; each bit represents a certain feature.
   If you want to trace something, look up the bit value(s) in the table 
   below, add the values together and supply that to the trace variable.

   Value  Value   Description					   Default
   (dec)  (hex)
       1    0x1   Module initialization; this will log messages       On
                  while loading and unloading the module

       2    0x2   probe() and disconnect() traces                     On

       4    0x4   Trace open() and close() calls                      Off

       8    0x8   read(), mmap() and associated ioctl() calls         Off

      16   0x10   Memory allocation of buffers, etc.                  Off

      32   0x20   Showing underflow, overflow and Dumping frame       On
                  messages

      64   0x40   Show viewport and image sizes                       Off


   For example, to trace the open() & read() fuctions, sum 8 + 4 = 12,
   so you would supply trace=12 during insmod or modprobe. If
   you want to turn the initialization and probing tracing off, set trace=0.
   The default value for trace is 35 (0x23).

   Example:
     
     # modprobe pwc size=cif fps=15 power_save=1

The fbufs, mbufs and trace parameters are global and apply to all connected
cameras. Each camera has its own set of buffers.

size, fps, palette only specify defaults when you open() the device; this is
to accommodate some tools that don't set the size or colour palette. You can
change these settings after open() with the Video4Linux ioctl() calls. The
default of defaults is QCIF size at 10 fps, BGR order.

The compression parameter is semiglobal; it sets the initial compression
preference for all camera's, but this parameter can be set per camera with
the VIDIOCPWCSCQUAL ioctl() call.

All parameters are optional.


